@xopcai/xopc 0.0.321 → 0.0.324

package/dist/src/agent-catalog/repository.js

@@ -0,0 +1,319 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { init_sqlite } from "../storage/sqlite/index.js";
+import { AgentDefaultsSchema, AgentEntrySchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_SKILL_POLICY } from "../agent-config/schema.js";
+import { init_agent_config } from "../agent-config/index.js";
+import { DEFAULT_AGENT_ID, init_id, normalizeAgentId } from "./id.js";
+import { BindingsSchema, init_binding_schema } from "../routing/binding-schema.js";
+import { randomUUID } from "node:crypto";
+//#region src/agent-catalog/repository.ts
+function parseObject(value, label) {
+	const parsed = JSON.parse(value);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label} must contain a JSON object`);
+	return parsed;
+}
+function rowToAgent(row) {
+	const overrides = parseObject(row.overrides_json, `Agent ${row.id} overrides`);
+	return {
+		...AgentEntrySchema.parse({
+			id: row.id,
+			enabled: row.enabled === 1,
+			...row.workspace_override ? { workspace: row.workspace_override } : {},
+			...row.profile_json ? { profile: JSON.parse(row.profile_json) } : {},
+			...overrides
+		}),
+		revision: row.revision,
+		provisioningState: row.provisioning_state,
+		...row.provisioning_error ? { provisioningError: row.provisioning_error } : {},
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+		...row.deleted_at === null ? {} : { deletedAt: row.deleted_at }
+	};
+}
+function splitEntry(entry) {
+	const { id: _id, enabled: _enabled, workspace, profile, ...overrides } = AgentEntrySchema.parse(entry);
+	return {
+		workspace: workspace ?? null,
+		profileJson: profile ? JSON.stringify(profile) : null,
+		overridesJson: JSON.stringify(overrides)
+	};
+}
+function requireSettings() {
+	const row = getSqliteDatabase().prepare(`SELECT default_agent_id, defaults_json, revision, created_at, updated_at
+    FROM agent_catalog_settings WHERE singleton_id = 1`).get();
+	if (!row) throw new Error("Agent catalog is not initialized");
+	return {
+		defaultAgentId: row.default_agent_id,
+		defaults: AgentDefaultsSchema.parse(JSON.parse(row.defaults_json)),
+		revision: row.revision,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function bumpCatalogRevision(now) {
+	const result = getSqliteDatabase().prepare(`UPDATE agent_catalog_settings
+    SET revision = revision + 1, updated_at = ? WHERE singleton_id = 1`).run(now);
+	if (Number(result.changes) !== 1) throw new Error("Agent catalog is not initialized");
+}
+function defaultAgentDefaults() {
+	return structuredClone(DEFAULT_AGENT_DEFAULTS);
+}
+var DEFAULT_AGENT_DEFAULTS, AgentCatalogRepository;
+var init_repository = __esmMin((() => {
+	init_agent_config();
+	init_id();
+	init_binding_schema();
+	init_sqlite();
+	DEFAULT_AGENT_DEFAULTS = AgentDefaultsSchema.parse({
+		models: {
+			chat: {
+				primary: DEFAULT_AGENT_MODEL_REF,
+				fallbacks: []
+			},
+			intents: {}
+		},
+		skills: DEFAULT_SKILL_POLICY
+	});
+	AgentCatalogRepository = class {
+		ensureInitialized(defaults = DEFAULT_AGENT_DEFAULTS) {
+			runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				db.prepare(`INSERT OR IGNORE INTO agents
+        (id, enabled, workspace_override, profile_json, overrides_json, provisioning_state,
+         provisioning_error, revision, created_at, updated_at, deleted_at)
+        VALUES (?, 1, NULL, ?, '{}', 'pending', NULL, 1, ?, ?, NULL)`).run(DEFAULT_AGENT_ID, JSON.stringify({ name: "Main" }), now, now);
+				db.prepare(`INSERT OR IGNORE INTO agent_catalog_settings
+        (singleton_id, default_agent_id, defaults_json, revision, created_at, updated_at)
+        VALUES (1, ?, ?, 1, ?, ?)`).run(DEFAULT_AGENT_ID, JSON.stringify(AgentDefaultsSchema.parse(defaults)), now, now);
+				db.prepare(`INSERT OR IGNORE INTO agent_provisioning_jobs
+        (agent_id, operation, state, attempts, last_error, created_at, updated_at)
+        VALUES (?, 'provision', 'pending', 0, NULL, ?, ?)`).run(DEFAULT_AGENT_ID, now, now);
+			});
+		}
+		getSettings() {
+			return requireSettings();
+		}
+		list(options = {}) {
+			const clauses = [];
+			if (!options.includeDeleted) clauses.push("deleted_at IS NULL");
+			if (options.readyOnly) clauses.push("provisioning_state = 'ready'");
+			const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+			return getSqliteDatabase().prepare(`SELECT * FROM agents ${where} ORDER BY id`).all().map(rowToAgent);
+		}
+		get(id, options = {}) {
+			const agentId = normalizeAgentId(id);
+			const row = getSqliteDatabase().prepare(`SELECT * FROM agents WHERE id = ?${options.includeDeleted ? "" : " AND deleted_at IS NULL"}`).get(agentId);
+			return row ? rowToAgent(row) : null;
+		}
+		snapshot() {
+			const settings = requireSettings();
+			const agents = this.list({ readyOnly: true }).map(({ revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry }) => entry);
+			const bindings = getSqliteDatabase().prepare(`SELECT id, agent_id, position, rule_json
+      FROM agent_bindings ORDER BY position, id`).all().map((row) => ({
+				id: row.id,
+				agentId: row.agent_id,
+				...parseObject(row.rule_json, `Binding ${row.id}`)
+			}));
+			const surfaceDefaults = Object.fromEntries(getSqliteDatabase().prepare("SELECT surface, agent_id FROM agent_surface_defaults ORDER BY surface").all().map((row) => [row.surface, row.agent_id]));
+			return {
+				revision: settings.revision,
+				defaultAgentId: settings.defaultAgentId,
+				defaults: settings.defaults,
+				agents,
+				bindings: BindingsSchema.parse(bindings),
+				surfaceDefaults
+			};
+		}
+		create(entryInput, options = {}) {
+			const entry = AgentEntrySchema.parse(entryInput);
+			const id = normalizeAgentId(entry.id);
+			if (id !== entry.id) throw new Error(`Invalid normalized Agent id: ${entry.id}`);
+			return runSqliteWriteTransaction((db) => {
+				if (db.prepare("SELECT 1 FROM agents WHERE id = ?").get(id)) throw new Error(`Agent "${id}" already exists`);
+				const now = Date.now();
+				const parts = splitEntry(entry);
+				const state = options.ready ? "ready" : "pending";
+				db.prepare(`INSERT INTO agents
+        (id, enabled, workspace_override, profile_json, overrides_json, provisioning_state,
+         provisioning_error, revision, created_at, updated_at, deleted_at)
+        VALUES (?, ?, ?, ?, ?, ?, NULL, 1, ?, ?, NULL)`).run(id, entry.enabled === false ? 0 : 1, parts.workspace, parts.profileJson, parts.overridesJson, state, now, now);
+				if (!options.ready) db.prepare(`INSERT INTO agent_provisioning_jobs
+          (agent_id, operation, state, attempts, last_error, created_at, updated_at)
+          VALUES (?, 'provision', 'pending', 0, NULL, ?, ?)`).run(id, now, now);
+				bumpCatalogRevision(now);
+				return rowToAgent(db.prepare("SELECT * FROM agents WHERE id = ?").get(id));
+			});
+		}
+		update(id, expectedRevision, entryInput, options = {}) {
+			const agentId = normalizeAgentId(id);
+			const entry = AgentEntrySchema.parse(entryInput);
+			if (entry.id !== agentId) throw new Error("Agent id cannot be changed");
+			return runSqliteWriteTransaction((db) => {
+				if (entry.enabled === false) {
+					if (requireSettings().defaultAgentId === agentId) throw new Error("Default Agent cannot be disabled");
+				}
+				const parts = splitEntry(entry);
+				const now = Date.now();
+				const result = db.prepare(`UPDATE agents SET enabled = ?, workspace_override = ?, profile_json = ?,
+        overrides_json = ?, provisioning_state = ?, provisioning_error = NULL,
+        revision = revision + 1, updated_at = ?
+        WHERE id = ? AND revision = ? AND deleted_at IS NULL`).run(entry.enabled === false ? 0 : 1, parts.workspace, parts.profileJson, parts.overridesJson, options.reprovision ? "pending" : "ready", now, agentId, expectedRevision);
+				if (Number(result.changes) !== 1) throw new Error("Agent revision conflict");
+				if (options.reprovision) db.prepare(`INSERT INTO agent_provisioning_jobs
+          (agent_id, operation, state, attempts, last_error, created_at, updated_at)
+          VALUES (?, 'provision', 'pending', 0, NULL, ?, ?)
+          ON CONFLICT(agent_id) DO UPDATE SET operation = 'provision', state = 'pending',
+          attempts = 0, last_error = NULL, updated_at = excluded.updated_at`).run(agentId, now, now);
+				bumpCatalogRevision(now);
+				return rowToAgent(db.prepare("SELECT * FROM agents WHERE id = ?").get(agentId));
+			});
+		}
+		setDefault(agentIdRaw, expectedRevision) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			return runSqliteWriteTransaction((db) => {
+				const agent = db.prepare(`SELECT enabled, provisioning_state, deleted_at FROM agents WHERE id = ?`).get(agentId);
+				if (!agent || agent.enabled !== 1 || agent.provisioning_state !== "ready" || agent.deleted_at !== null) throw new Error(`Agent "${agentId}" is not available`);
+				const now = Date.now();
+				const result = db.prepare(`UPDATE agent_catalog_settings SET default_agent_id = ?,
+        revision = revision + 1, updated_at = ? WHERE singleton_id = 1 AND revision = ?`).run(agentId, now, expectedRevision);
+				if (Number(result.changes) !== 1) throw new Error("Agent catalog revision conflict");
+				return requireSettings();
+			});
+		}
+		updateDefaults(defaultsInput, expectedRevision) {
+			const defaults = AgentDefaultsSchema.parse(defaultsInput);
+			return runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				const result = db.prepare(`UPDATE agent_catalog_settings SET defaults_json = ?,
+        revision = revision + 1, updated_at = ? WHERE singleton_id = 1 AND revision = ?`).run(JSON.stringify(defaults), now, expectedRevision);
+				if (Number(result.changes) !== 1) throw new Error("Agent catalog revision conflict");
+				return requireSettings();
+			});
+		}
+		replaceBindings(bindingsInput) {
+			const bindings = BindingsSchema.parse(bindingsInput);
+			return runSqliteWriteTransaction((db) => {
+				for (const binding of bindings) {
+					const agentId = normalizeAgentId(binding.agentId);
+					if (!db.prepare(`SELECT 1 FROM agents WHERE id = ? AND enabled = 1
+          AND provisioning_state = 'ready' AND deleted_at IS NULL`).get(agentId)) throw new Error(`Agent "${agentId}" is not available`);
+				}
+				db.prepare("DELETE FROM agent_bindings").run();
+				const now = Date.now();
+				const insert = db.prepare(`INSERT INTO agent_bindings
+        (id, agent_id, position, rule_json, revision, created_at, updated_at)
+        VALUES (?, ?, ?, ?, 1, ?, ?)`);
+				bindings.forEach((binding, position) => {
+					const { id, agentId, ...rule } = binding;
+					insert.run(id ?? randomUUID(), normalizeAgentId(agentId), position, JSON.stringify(rule), now, now);
+				});
+				db.prepare(`UPDATE agent_catalog_settings SET revision = revision + 1, updated_at = ? WHERE singleton_id = 1`).run(now);
+				return this.snapshot().bindings;
+			});
+		}
+		setSurfaceDefault(surfaceRaw, agentIdRaw) {
+			const surface = surfaceRaw.trim();
+			if (!surface) throw new Error("Surface is required");
+			const agentId = normalizeAgentId(agentIdRaw);
+			runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				if (!db.prepare(`SELECT 1 FROM agents WHERE id = ? AND enabled = 1
+        AND provisioning_state = 'ready' AND deleted_at IS NULL`).get(agentId)) throw new Error(`Agent "${agentId}" is not available`);
+				db.prepare(`INSERT INTO agent_surface_defaults(surface, agent_id, revision, updated_at)
+        VALUES (?, ?, 1, ?) ON CONFLICT(surface) DO UPDATE SET agent_id = excluded.agent_id,
+        revision = agent_surface_defaults.revision + 1, updated_at = excluded.updated_at`).run(surface, agentId, now);
+				db.prepare(`UPDATE agent_catalog_settings SET revision = revision + 1, updated_at = ? WHERE singleton_id = 1`).run(now);
+			});
+		}
+		clearSurfaceDefault(surfaceRaw) {
+			const surface = surfaceRaw.trim();
+			if (!surface) throw new Error("Surface is required");
+			runSqliteWriteTransaction((db) => {
+				const result = db.prepare("DELETE FROM agent_surface_defaults WHERE surface = ?").run(surface);
+				if (Number(result.changes) > 0) bumpCatalogRevision(Date.now());
+			});
+		}
+		markProvisioned(agentIdRaw) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			return runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				const result = db.prepare(`UPDATE agents SET provisioning_state = 'ready', provisioning_error = NULL,
+        revision = revision + 1, updated_at = ? WHERE id = ? AND deleted_at IS NULL`).run(now, agentId);
+				if (Number(result.changes) !== 1) throw new Error(`Agent "${agentId}" not found`);
+				db.prepare("DELETE FROM agent_provisioning_jobs WHERE agent_id = ?").run(agentId);
+				bumpCatalogRevision(now);
+				return rowToAgent(db.prepare("SELECT * FROM agents WHERE id = ?").get(agentId));
+			});
+		}
+		markProvisioningFailed(agentIdRaw, errorMessage) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				const bounded = errorMessage.slice(0, 1e3);
+				db.prepare(`UPDATE agents SET provisioning_state = 'error', provisioning_error = ?,
+        revision = revision + 1, updated_at = ? WHERE id = ? AND deleted_at IS NULL`).run(bounded, now, agentId);
+				db.prepare(`UPDATE agent_provisioning_jobs SET state = 'failed', attempts = attempts + 1,
+        last_error = ?, updated_at = ? WHERE agent_id = ?`).run(bounded, now, agentId);
+				bumpCatalogRevision(now);
+			});
+		}
+		listPendingProvisioningAgentIds() {
+			return getSqliteDatabase().prepare(`SELECT agent_id FROM agent_provisioning_jobs
+      WHERE operation = 'provision' AND state IN ('pending', 'failed') ORDER BY created_at`).all().map((row) => row.agent_id);
+		}
+		listPendingPurgeAgentIds() {
+			return getSqliteDatabase().prepare(`SELECT agent_id FROM agent_provisioning_jobs
+      WHERE operation = 'purge' AND state IN ('pending', 'failed') ORDER BY created_at`).all().map((row) => row.agent_id);
+		}
+		markPurged(agentIdRaw) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			runSqliteWriteTransaction((db) => {
+				const result = db.prepare("DELETE FROM agents WHERE id = ? AND deleted_at IS NOT NULL").run(agentId);
+				if (Number(result.changes) !== 1) throw new Error(`Deleted Agent "${agentId}" not found`);
+				bumpCatalogRevision(Date.now());
+			});
+		}
+		markPurgeFailed(agentIdRaw, errorMessage) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			runSqliteWriteTransaction((db) => {
+				const now = Date.now();
+				const bounded = errorMessage.slice(0, 1e3);
+				db.prepare(`UPDATE agents SET provisioning_state = 'error', provisioning_error = ?,
+        revision = revision + 1, updated_at = ? WHERE id = ? AND deleted_at IS NOT NULL`).run(bounded, now, agentId);
+				db.prepare(`UPDATE agent_provisioning_jobs SET state = 'failed', attempts = attempts + 1,
+        last_error = ?, updated_at = ? WHERE agent_id = ? AND operation = 'purge'`).run(bounded, now, agentId);
+				bumpCatalogRevision(now);
+			});
+		}
+		delete(agentIdRaw, options = {}) {
+			const agentId = normalizeAgentId(agentIdRaw);
+			return runSqliteWriteTransaction((db) => {
+				const settings = requireSettings();
+				if (agentId === "main") throw new Error(`Agent id "${DEFAULT_AGENT_ID}" is reserved for the primary Agent`);
+				if (settings.defaultAgentId === agentId) throw new Error(`Agent "${agentId}" is the global default Agent`);
+				const surface = db.prepare("SELECT surface FROM agent_surface_defaults WHERE agent_id = ? LIMIT 1").get(agentId);
+				if (surface) throw new Error(`Agent "${agentId}" is the ${surface.surface} default Agent`);
+				const row = db.prepare("SELECT * FROM agents WHERE id = ? AND deleted_at IS NULL").get(agentId);
+				if (!row) throw new Error(`Agent "${agentId}" not found`);
+				const removedBindings = Number(db.prepare("DELETE FROM agent_bindings WHERE agent_id = ?").run(agentId).changes);
+				db.prepare("DELETE FROM agent_provisioning_jobs WHERE agent_id = ?").run(agentId);
+				const now = Date.now();
+				if (options.purge) {
+					db.prepare(`UPDATE agents SET enabled = 0, provisioning_state = 'pending', provisioning_error = NULL,
+          revision = revision + 1, updated_at = ?, deleted_at = ? WHERE id = ?`).run(now, now, agentId);
+					db.prepare(`INSERT INTO agent_provisioning_jobs
+          (agent_id, operation, state, attempts, last_error, created_at, updated_at)
+          VALUES (?, 'purge', 'pending', 0, NULL, ?, ?)`).run(agentId, now, now);
+				} else db.prepare("DELETE FROM agents WHERE id = ?").run(agentId);
+				bumpCatalogRevision(now);
+				return {
+					agent: options.purge ? rowToAgent(db.prepare("SELECT * FROM agents WHERE id = ?").get(agentId)) : rowToAgent(row),
+					removedBindings
+				};
+			});
+		}
+	};
+}));
+//#endregion
+init_repository();
+export { AgentCatalogRepository, defaultAgentDefaults, init_repository };

package/dist/src/agent-catalog/service.d.ts

@@ -0,0 +1,33 @@
+import type { AgentDefaults, AgentEntry } from '../agent-config/index.js';
+import type { BindingRule } from '../routing/binding-schema.js';
+import { AgentCatalogRepository } from './repository.js';
+import type { AgentCatalogSettings, StoredAgent } from './types.js';
+export declare class AgentCatalogService {
+    private readonly repository;
+    constructor(repository?: AgentCatalogRepository);
+    create(entry: AgentEntry): Promise<StoredAgent>;
+    resumePendingProvisioning(): Promise<void>;
+    /** Startup recovery for catalog rows committed before their directories were provisioned. */
+    resumePendingProvisioningSync(): void;
+    update(agentIdRaw: string, patch: Partial<Omit<AgentEntry, 'id'>>): Promise<StoredAgent>;
+    /** Remove data for an Agent that has already been deleted from the catalog. */
+    purgeEntryData(entry: AgentEntry, defaultAgentId: string): Promise<void>;
+    validatePurgeEntry(entry: AgentEntry, defaultAgentId: string): void;
+    resumePendingPurge(): Promise<string[]>;
+    private resumePendingPurgeSync;
+    setDefault(agentId: string): AgentCatalogSettings;
+    updateDefaults(defaults: AgentDefaults): AgentCatalogSettings;
+    replaceBindings(bindings: BindingRule[]): BindingRule[];
+    setSurfaceDefault(surface: string, agentId: string): void;
+    clearSurfaceDefault(surface: string): void;
+    delete(agentIdRaw: string, options?: {
+        purge?: boolean;
+    }): Promise<{
+        removedBindings: number;
+    }>;
+    private provision;
+    private provisionSync;
+    private purgeEntryDataSync;
+    private assertSafeWorkspacePurge;
+    private assertPurgeTargetsAreNotShared;
+}

package/dist/src/agent-catalog/service.js

@@ -0,0 +1,202 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { init_id, normalizeAgentId } from "./id.js";
+import { AgentCatalogRepository, init_repository } from "./repository.js";
+import { init_workspace_defaults, resolveDefaultAgentWorkspaceDir } from "../config/workspace-defaults.js";
+import { init_agent_scope, resolveAgentDir, resolveAgentHomeDir, resolveAgentProfileDir, resolveUserPath } from "../agent/agent-scope.js";
+import { seedAgentProfileMarkdownFiles } from "../agent/context/workspace-seed.js";
+import { isAbsolute, join, parse, relative, resolve } from "node:path";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+//#region src/agent-catalog/service.ts
+init_agent_scope();
+init_paths_state();
+init_workspace_defaults();
+init_id();
+init_repository();
+function workspaceForEntry(entry, defaultAgentId) {
+	if (entry.workspace?.trim()) return resolveUserPath(entry.workspace);
+	if (entry.id === defaultAgentId) return resolveDefaultAgentWorkspaceDir(process.env);
+	return join(resolveStateDir(process.env), `workspace-${entry.id}`);
+}
+var AgentCatalogService = class {
+	constructor(repository = new AgentCatalogRepository()) {
+		this.repository = repository;
+	}
+	async create(entry) {
+		const pending = this.repository.create(entry);
+		try {
+			await this.provision(pending);
+			return this.repository.markProvisioned(pending.id);
+		} catch (error) {
+			this.repository.markProvisioningFailed(pending.id, error instanceof Error ? error.message : String(error));
+			throw error;
+		}
+	}
+	async resumePendingProvisioning() {
+		for (const agentId of this.repository.listPendingProvisioningAgentIds()) {
+			const agent = this.repository.get(agentId);
+			if (!agent) continue;
+			try {
+				await this.provision(agent);
+				this.repository.markProvisioned(agentId);
+			} catch (error) {
+				this.repository.markProvisioningFailed(agentId, error instanceof Error ? error.message : String(error));
+			}
+		}
+		await this.resumePendingPurge();
+	}
+	/** Startup recovery for catalog rows committed before their directories were provisioned. */
+	resumePendingProvisioningSync() {
+		for (const agentId of this.repository.listPendingProvisioningAgentIds()) {
+			const agent = this.repository.get(agentId);
+			if (!agent) continue;
+			try {
+				this.provisionSync(agent);
+				this.repository.markProvisioned(agentId);
+			} catch (error) {
+				this.repository.markProvisioningFailed(agentId, error instanceof Error ? error.message : String(error));
+			}
+		}
+		this.resumePendingPurgeSync();
+	}
+	async update(agentIdRaw, patch) {
+		const agentId = normalizeAgentId(agentIdRaw);
+		const current = this.repository.get(agentId);
+		if (!current) throw new Error(`Agent "${agentId}" not found`);
+		const { revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry } = current;
+		const next = {
+			...entry,
+			...patch,
+			id: agentId
+		};
+		await this.provision(next);
+		return this.repository.update(agentId, revision, next);
+	}
+	/** Remove data for an Agent that has already been deleted from the catalog. */
+	async purgeEntryData(entry, defaultAgentId) {
+		if (entry.id === "main") throw new Error("Refusing to purge the primary Agent");
+		const workspace = workspaceForEntry(entry, defaultAgentId);
+		const home = resolveAgentHomeDir(entry.id);
+		this.assertSafeWorkspacePurge(workspace);
+		this.assertPurgeTargetsAreNotShared(entry.id, [home, workspace], defaultAgentId);
+		if (existsSync(home)) await rm(home, {
+			recursive: true,
+			force: true
+		});
+		if (existsSync(workspace) && resolve(workspace) !== resolve(home)) await rm(workspace, {
+			recursive: true,
+			force: true
+		});
+	}
+	validatePurgeEntry(entry, defaultAgentId) {
+		if (entry.id === "main") throw new Error("Refusing to purge the primary Agent");
+		const workspace = workspaceForEntry(entry, defaultAgentId);
+		this.assertSafeWorkspacePurge(workspace);
+		this.assertPurgeTargetsAreNotShared(entry.id, [resolveAgentHomeDir(entry.id), workspace], defaultAgentId);
+	}
+	async resumePendingPurge() {
+		const failed = [];
+		for (const agentId of this.repository.listPendingPurgeAgentIds()) {
+			const agent = this.repository.get(agentId, { includeDeleted: true });
+			if (!agent) continue;
+			try {
+				await this.purgeEntryData(agent, this.repository.getSettings().defaultAgentId);
+				this.repository.markPurged(agentId);
+			} catch (error) {
+				this.repository.markPurgeFailed(agentId, error instanceof Error ? error.message : String(error));
+				failed.push(agentId);
+			}
+		}
+		return failed;
+	}
+	resumePendingPurgeSync() {
+		for (const agentId of this.repository.listPendingPurgeAgentIds()) {
+			const agent = this.repository.get(agentId, { includeDeleted: true });
+			if (!agent) continue;
+			try {
+				this.purgeEntryDataSync(agent, this.repository.getSettings().defaultAgentId);
+				this.repository.markPurged(agentId);
+			} catch (error) {
+				this.repository.markPurgeFailed(agentId, error instanceof Error ? error.message : String(error));
+			}
+		}
+	}
+	setDefault(agentId) {
+		const settings = this.repository.getSettings();
+		return this.repository.setDefault(agentId, settings.revision);
+	}
+	updateDefaults(defaults) {
+		const settings = this.repository.getSettings();
+		return this.repository.updateDefaults(defaults, settings.revision);
+	}
+	replaceBindings(bindings) {
+		return this.repository.replaceBindings(bindings);
+	}
+	setSurfaceDefault(surface, agentId) {
+		this.repository.setSurfaceDefault(surface, agentId);
+	}
+	clearSurfaceDefault(surface) {
+		this.repository.clearSurfaceDefault(surface);
+	}
+	async delete(agentIdRaw, options = {}) {
+		const agentId = normalizeAgentId(agentIdRaw);
+		const current = this.repository.get(agentId);
+		if (!current) throw new Error(`Agent "${agentId}" not found`);
+		if (options.purge) this.validatePurgeEntry(current, this.repository.getSettings().defaultAgentId);
+		const result = this.repository.delete(agentId, options);
+		if (options.purge) {
+			if ((await this.resumePendingPurge()).includes(agentId)) throw new Error(`Agent "${agentId}" was deleted; data purge is pending retry`);
+		}
+		return { removedBindings: result.removedBindings };
+	}
+	async provision(entry) {
+		const workspace = workspaceForEntry(entry, this.repository.getSettings().defaultAgentId);
+		const profileDir = resolveAgentProfileDir(entry.id);
+		await mkdir(workspace, { recursive: true });
+		await mkdir(resolveAgentDir(entry.id), { recursive: true });
+		await mkdir(profileDir, { recursive: true });
+		seedAgentProfileMarkdownFiles(profileDir, workspace, { displayName: entry.profile?.name ?? entry.id });
+	}
+	provisionSync(entry) {
+		const workspace = workspaceForEntry(entry, this.repository.getSettings().defaultAgentId);
+		const profileDir = resolveAgentProfileDir(entry.id);
+		mkdirSync(workspace, { recursive: true });
+		mkdirSync(resolveAgentDir(entry.id), { recursive: true });
+		mkdirSync(profileDir, { recursive: true });
+		seedAgentProfileMarkdownFiles(profileDir, workspace, { displayName: entry.profile?.name ?? entry.id });
+	}
+	purgeEntryDataSync(entry, defaultAgentId) {
+		if (entry.id === "main") throw new Error("Refusing to purge the primary Agent");
+		const workspace = workspaceForEntry(entry, defaultAgentId);
+		const home = resolveAgentHomeDir(entry.id);
+		this.assertSafeWorkspacePurge(workspace);
+		this.assertPurgeTargetsAreNotShared(entry.id, [home, workspace], defaultAgentId);
+		if (existsSync(home)) rmSync(home, {
+			recursive: true,
+			force: true
+		});
+		if (existsSync(workspace) && resolve(workspace) !== resolve(home)) rmSync(workspace, {
+			recursive: true,
+			force: true
+		});
+	}
+	assertSafeWorkspacePurge(workspaceRaw) {
+		const workspace = resolve(workspaceRaw);
+		const stateDir = resolve(resolveStateDir(process.env));
+		const rel = relative(workspace, stateDir);
+		if (workspace === parse(workspace).root || workspace === stateDir || rel === "" || !rel.startsWith("..") && !isAbsolute(rel)) throw new Error(`Refusing to purge unsafe workspace path: ${workspace}`);
+	}
+	assertPurgeTargetsAreNotShared(agentId, targetsRaw, defaultAgentId) {
+		const targets = [...new Set(targetsRaw.map((target) => resolve(target)))];
+		for (const other of this.repository.list()) {
+			if (other.id === agentId) continue;
+			const otherWorkspace = resolve(workspaceForEntry(other, defaultAgentId));
+			if (targets.some((target) => {
+				const rel = relative(target, otherWorkspace);
+				return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+			})) throw new Error(`Refusing to purge workspace used by Agent "${other.id}"`);
+		}
+	}
+};
+//#endregion
+export { AgentCatalogService };

package/dist/src/agent-catalog/test-support.d.ts

@@ -0,0 +1,14 @@
+import type { AgentDefaults, AgentEntry } from '../agent-config/index.js';
+import type { BindingRule } from '../routing/binding-schema.js';
+import { AgentCatalogRepository } from './repository.js';
+export type TestAgentCatalogSeed = {
+    defaults?: AgentDefaults;
+    defaultAgentId?: string;
+    agents?: AgentEntry[];
+    bindings?: BindingRule[];
+    surfaceDefaults?: Record<string, string>;
+};
+/** Build an isolated, ready in-memory Agent catalog for a unit test. */
+export declare function initializeTestAgentCatalog(seed?: TestAgentCatalogSeed): AgentCatalogRepository;
+/** Seed the currently open test database with a ready Agent catalog. */
+export declare function seedTestAgentCatalog(seed?: TestAgentCatalogSeed): AgentCatalogRepository;

package/dist/src/agent-catalog/test-support.js

@@ -0,0 +1,34 @@
+import { closeXopcDatabase, openXopcDatabase } from "../storage/sqlite/connection.js";
+import { init_sqlite } from "../storage/sqlite/index.js";
+import { AgentCatalogRepository, init_repository } from "./repository.js";
+//#region src/agent-catalog/test-support.ts
+init_sqlite();
+init_repository();
+/** Build an isolated, ready in-memory Agent catalog for a unit test. */
+function initializeTestAgentCatalog(seed = {}) {
+	closeXopcDatabase();
+	openXopcDatabase({ path: ":memory:" });
+	return seedTestAgentCatalog(seed);
+}
+/** Seed the currently open test database with a ready Agent catalog. */
+function seedTestAgentCatalog(seed = {}) {
+	const repository = new AgentCatalogRepository();
+	repository.ensureInitialized(seed.defaults);
+	const entries = seed.agents ?? [{
+		id: "main",
+		enabled: true
+	}];
+	const main = entries.find((entry) => entry.id === "main");
+	if (main) {
+		const stored = repository.get("main");
+		repository.update("main", stored.revision, main);
+	}
+	repository.markProvisioned("main");
+	for (const entry of entries) if (entry.id !== "main") repository.create(entry, { ready: true });
+	if (seed.defaultAgentId && seed.defaultAgentId !== "main") repository.setDefault(seed.defaultAgentId, repository.getSettings().revision);
+	if (seed.bindings) repository.replaceBindings(seed.bindings);
+	for (const [surface, agentId] of Object.entries(seed.surfaceDefaults ?? {})) repository.setSurfaceDefault(surface, agentId);
+	return repository;
+}
+//#endregion
+export { initializeTestAgentCatalog, seedTestAgentCatalog };

package/dist/src/agent-catalog/types.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDefaults, AgentEntry } from '../agent-config/index.js';
+import type { BindingRule } from '../routing/binding-schema.js';
+export type AgentProvisioningState = 'pending' | 'ready' | 'error';
+export interface StoredAgent extends AgentEntry {
+    revision: number;
+    provisioningState: AgentProvisioningState;
+    provisioningError?: string;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt?: number;
+}
+export interface AgentCatalogSnapshot {
+    revision: number;
+    defaultAgentId: string;
+    defaults: AgentDefaults;
+    agents: AgentEntry[];
+    bindings: BindingRule[];
+    surfaceDefaults: Record<string, string>;
+}
+export interface AgentCatalogSettings {
+    defaultAgentId: string;
+    defaults: AgentDefaults;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}

package/dist/src/agent-catalog/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/agent-config/index.js

@@ -1,5 +1,5 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { AgentDefaultsSchema, AgentEntrySchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, AgentsConfigSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_schema } from "./schema.js";
+import { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_schema } from "./schema.js";
 import { init_resolver, resolveEffectiveAgentConfig } from "./resolver.js";
 //#region src/agent-config/index.ts
 var init_agent_config = __esmMin((() => {
@@ -8,4 +8,4 @@ var init_agent_config = __esmMin((() => {
 }));
 //#endregion
 init_agent_config();
-export { AgentDefaultsSchema, AgentEntrySchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, AgentsConfigSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_agent_config, resolveEffectiveAgentConfig };
+export { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_agent_config, resolveEffectiveAgentConfig };