@xopcai/xopc 0.0.321 → 0.0.324

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

@@ -0,0 +1,101 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+//#region src/agent-catalog/id.ts
+/** Path-safe agent id. */
+function normalizeAgentId(value) {
+	const trimmed = (value ?? "").trim();
+	if (!trimmed) return DEFAULT_AGENT_ID;
+	const normalized = trimmed.toLowerCase();
+	if (VALID_ID_RE.test(trimmed)) return normalized;
+	return normalized.replace(INVALID_CHARS_RE, "-").replace(LEADING_DASH_RE, "").replace(TRAILING_DASH_RE, "").slice(0, 64) || "main";
+}
+function hashAgentDisplayName(value) {
+	let hash = 2166136261;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36).padStart(7, "0");
+}
+/** Derive a folder-safe id, including for display names with no ASCII characters. */
+function deriveAgentIdFromDisplayName(displayName) {
+	const normalizedName = displayName.trim().normalize("NFKC").toLowerCase();
+	const asciiId = normalizeAgentId(normalizedName);
+	if (asciiId !== "main" || normalizedName === "main") return asciiId;
+	return normalizedName ? `agent-${hashAgentDisplayName(normalizedName)}` : DEFAULT_AGENT_ID;
+}
+/** Validate a new Agent id before it becomes a filesystem path segment. */
+function validateAgentIdForNewAgent(explicitId, displayNameForDerivation) {
+	const explicit = explicitId?.trim();
+	if (explicit) {
+		const id = explicit.toLowerCase();
+		if (!STRICT_AGENT_ID_RE.test(id)) return {
+			ok: false,
+			error: "Invalid agent id: use 1–64 characters; letters, digits, underscores, and hyphens only; start with a letter or digit."
+		};
+		if (id === "main") return {
+			ok: false,
+			error: `"${DEFAULT_AGENT_ID}" is reserved`
+		};
+		if (WINDOWS_RESERVED_AGENT_IDS.has(id)) return {
+			ok: false,
+			error: `Agent id "${id}" is reserved (Windows device name).`
+		};
+		return {
+			ok: true,
+			agentId: id
+		};
+	}
+	const agentId = deriveAgentIdFromDisplayName(displayNameForDerivation);
+	if (agentId === "main") return {
+		ok: false,
+		error: "Display name cannot produce a valid agent folder id. Set an explicit Agent id (letters, digits, underscores, hyphens only)."
+	};
+	if (WINDOWS_RESERVED_AGENT_IDS.has(agentId)) return {
+		ok: false,
+		error: `That display name resolves to "${agentId}", which is reserved. Use a different display name or set an explicit Agent id.`
+	};
+	if (!STRICT_AGENT_ID_RE.test(agentId)) return {
+		ok: false,
+		error: "Could not derive a folder-safe agent id from the display name. Set an explicit Agent id (letters, digits, underscores, hyphens only)."
+	};
+	return {
+		ok: true,
+		agentId
+	};
+}
+var DEFAULT_AGENT_ID, VALID_ID_RE, INVALID_CHARS_RE, LEADING_DASH_RE, TRAILING_DASH_RE, STRICT_AGENT_ID_RE, WINDOWS_RESERVED_AGENT_IDS;
+var init_id = __esmMin((() => {
+	DEFAULT_AGENT_ID = "main";
+	VALID_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+	INVALID_CHARS_RE = /[^a-z0-9_-]+/g;
+	LEADING_DASH_RE = /^-+/;
+	TRAILING_DASH_RE = /-+$/;
+	STRICT_AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+	WINDOWS_RESERVED_AGENT_IDS = new Set([
+		"con",
+		"prn",
+		"aux",
+		"nul",
+		"com1",
+		"com2",
+		"com3",
+		"com4",
+		"com5",
+		"com6",
+		"com7",
+		"com8",
+		"com9",
+		"lpt1",
+		"lpt2",
+		"lpt3",
+		"lpt4",
+		"lpt5",
+		"lpt6",
+		"lpt7",
+		"lpt8",
+		"lpt9"
+	]);
+}));
+//#endregion
+init_id();
+export { DEFAULT_AGENT_ID, STRICT_AGENT_ID_RE, deriveAgentIdFromDisplayName, init_id, normalizeAgentId, validateAgentIdForNewAgent };

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

@@ -0,0 +1,6 @@
+export * from './repository.js';
+export * from './types.js';
+export * from './id.js';
+export * from './service.js';
+export * from './capabilities.js';
+export * from './migrations/legacy-config-cutover.js';

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

@@ -0,0 +1,10 @@
+import { DEFAULT_AGENT_ID, STRICT_AGENT_ID_RE, deriveAgentIdFromDisplayName, init_id, normalizeAgentId, validateAgentIdForNewAgent } from "./id.js";
+import { AgentCatalogRepository, defaultAgentDefaults, init_repository } from "./repository.js";
+import { AgentCatalogService } from "./service.js";
+import { registerAgentCapabilities } from "./capabilities.js";
+import { cutoverLegacyAgentConfig } from "./migrations/legacy-config-cutover.js";
+//#region src/agent-catalog/index.ts
+init_repository();
+init_id();
+//#endregion
+export { AgentCatalogRepository, AgentCatalogService, DEFAULT_AGENT_ID, STRICT_AGENT_ID_RE, cutoverLegacyAgentConfig, defaultAgentDefaults, deriveAgentIdFromDisplayName, normalizeAgentId, registerAgentCapabilities, validateAgentIdForNewAgent };

package/dist/src/agent-catalog/migrations/legacy-config-cutover.d.ts

@@ -0,0 +1,11 @@
+export type AgentCatalogCutoverResult = {
+    status: 'not_needed' | 'migrated' | 'recovered';
+    importedAgents: number;
+    importedBindings: number;
+};
+export type AgentCatalogCutoverOptions = {
+    configPath: string;
+    /** Test-only crash injection after a durable stage. */
+    stopAfterStage?: 'database' | 'config';
+};
+export declare function cutoverLegacyAgentConfig(options: AgentCatalogCutoverOptions): AgentCatalogCutoverResult;

package/dist/src/agent-catalog/migrations/legacy-config-cutover.js

@@ -0,0 +1,195 @@
+import { backupDatabaseBeforeCutover, init_conversation_backup } from "../../storage/sqlite/migrations/conversation-backup.js";
+import { getXopcDatabase } from "../../storage/sqlite/connection.js";
+import { runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
+import { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_SKILL_POLICY } from "../../agent-config/schema.js";
+import { init_agent_config } from "../../agent-config/index.js";
+import { BindingsSchema, init_binding_schema } from "../../routing/binding-schema.js";
+import { AgentCatalogRepository, init_repository } from "../repository.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/agent-catalog/migrations/legacy-config-cutover.ts
+init_agent_config();
+init_write_file_atomic();
+init_binding_schema();
+init_sqlite();
+init_conversation_backup();
+init_repository();
+const MIGRATION_ID = "agent-catalog-sqlite-v1";
+const LegacyAgentsConfigSchema = z.object({
+	default: AgentIdSchema.default("main"),
+	defaults: AgentDefaultsSchema.default({
+		models: {
+			chat: {
+				primary: DEFAULT_AGENT_MODEL_REF,
+				fallbacks: []
+			},
+			intents: {}
+		},
+		skills: DEFAULT_SKILL_POLICY,
+		tools: {},
+		workflows: {},
+		runtime: {}
+	}),
+	list: z.array(AgentEntrySchema).default([{
+		id: "main",
+		enabled: true
+	}])
+}).strict().superRefine((value, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	value.list.forEach((agent, index) => {
+		if (seen.has(agent.id)) context.addIssue({
+			code: "custom",
+			path: [
+				"list",
+				index,
+				"id"
+			],
+			message: `duplicate agent id "${agent.id}"`
+		});
+		seen.add(agent.id);
+	});
+	if (!value.list.some((agent) => agent.id === value.default && agent.enabled)) context.addIssue({
+		code: "custom",
+		path: ["default"],
+		message: `default agent "${value.default}" must reference an enabled entry`
+	});
+});
+const DEFAULT_LEGACY_AGENTS = LegacyAgentsConfigSchema.parse({});
+const LegacyRootSchema = z.object({
+	agents: LegacyAgentsConfigSchema.default(DEFAULT_LEGACY_AGENTS),
+	bindings: BindingsSchema.optional(),
+	tui: z.object({ defaultAgent: z.string().min(1).optional() }).passthrough().optional()
+}).passthrough();
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+function sourceDigest(value) {
+	return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function splitEntry(entry) {
+	const { id: _id, enabled: _enabled, workspace: _workspace, profile, ...overrides } = entry;
+	return {
+		profileJson: profile ? JSON.stringify(profile) : null,
+		overridesJson: JSON.stringify(overrides)
+	};
+}
+function readRawConfig(configPath) {
+	if (!existsSync(configPath)) return {};
+	const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("xopc.json must contain a JSON object");
+	return parsed;
+}
+function migrationRow() {
+	return getXopcDatabase().db.prepare(`SELECT state, source_digest FROM application_migrations WHERE id = ?`).get(MIGRATION_ID);
+}
+function writeCleanConfig(configPath, raw) {
+	const next = structuredClone(raw);
+	delete next.agents;
+	delete next.bindings;
+	if (next.tui && typeof next.tui === "object" && !Array.isArray(next.tui)) {
+		const tui = { ...next.tui };
+		delete tui.defaultAgent;
+		if (Object.keys(tui).length) next.tui = tui;
+		else delete next.tui;
+	}
+	writeTextAtomicSync(configPath, `${JSON.stringify(next, null, 2)}\n`);
+}
+function insertBinding(binding, position, now) {
+	const { id, agentId, ...rule } = binding;
+	getXopcDatabase().db.prepare(`INSERT INTO agent_bindings
+    (id, agent_id, position, rule_json, revision, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 1, ?, ?)`).run(id ?? randomUUID(), agentId.trim().toLowerCase(), position, JSON.stringify(rule), now, now);
+}
+function importLegacyPayload(payload, digest, configBackupPath, databaseBackupPath) {
+	runSqliteWriteTransaction((db) => {
+		if (db.prepare("SELECT COUNT(*) AS count FROM agents").get().count > 0) throw new Error("Agent catalog already contains data before legacy import");
+		const now = Date.now();
+		const insertAgent = 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 (?, ?, ?, ?, ?, 'ready', NULL, 1, ?, ?, NULL)`);
+		for (const entry of payload.agents.list) {
+			const parts = splitEntry(entry);
+			insertAgent.run(entry.id, entry.enabled === false ? 0 : 1, entry.workspace ?? null, parts.profileJson, parts.overridesJson, now, now);
+		}
+		db.prepare(`INSERT INTO agent_catalog_settings
+      (singleton_id, default_agent_id, defaults_json, revision, created_at, updated_at)
+      VALUES (1, ?, ?, 1, ?, ?)`).run(payload.agents.default, JSON.stringify(payload.agents.defaults), now, now);
+		(payload.bindings ?? []).forEach((binding, index) => insertBinding(binding, index, now));
+		const tuiDefault = payload.tui?.defaultAgent?.trim().toLowerCase();
+		if (tuiDefault && payload.agents.list.some((entry) => entry.id === tuiDefault && entry.enabled !== false)) db.prepare(`INSERT INTO agent_surface_defaults(surface, agent_id, revision, updated_at)
+        VALUES ('tui', ?, 1, ?)`).run(tuiDefault, now);
+		db.prepare(`INSERT INTO application_migrations
+      (id, state, source_digest, source_backup_path, database_backup_path, error_json,
+       started_at, completed_at, updated_at)
+      VALUES (?, 'db_committed', ?, ?, ?, NULL, ?, NULL, ?)`).run(MIGRATION_ID, digest, configBackupPath, databaseBackupPath, now, now);
+	});
+}
+function completeMigration() {
+	const now = Date.now();
+	getXopcDatabase().db.prepare(`UPDATE application_migrations SET state = 'completed',
+    completed_at = ?, updated_at = ? WHERE id = ?`).run(now, now, MIGRATION_ID);
+}
+function cutoverLegacyAgentConfig(options) {
+	const raw = readRawConfig(options.configPath);
+	const legacyTui = raw.tui && typeof raw.tui === "object" && !Array.isArray(raw.tui) ? raw.tui : void 0;
+	const hasLegacyAgents = Object.hasOwn(raw, "agents") || Object.hasOwn(raw, "bindings") || Boolean(legacyTui && Object.hasOwn(legacyTui, "defaultAgent"));
+	const marker = migrationRow();
+	if (!hasLegacyAgents) {
+		if (marker?.state === "db_committed") {
+			completeMigration();
+			return {
+				status: "recovered",
+				importedAgents: 0,
+				importedBindings: 0
+			};
+		}
+		if (!marker) new AgentCatalogRepository().ensureInitialized();
+		return {
+			status: "not_needed",
+			importedAgents: 0,
+			importedBindings: 0
+		};
+	}
+	const payload = LegacyRootSchema.parse(raw);
+	const digest = sourceDigest({
+		agents: payload.agents,
+		bindings: payload.bindings ?? [],
+		tuiDefaultAgent: payload.tui?.defaultAgent
+	});
+	if (marker?.state === "completed") throw new Error("Legacy Agent configuration reappeared after the SQLite cutover completed");
+	if (marker?.state === "db_committed") {
+		if (marker.source_digest !== digest) throw new Error("Legacy Agent configuration changed during cutover recovery");
+		writeCleanConfig(options.configPath, raw);
+		if (options.stopAfterStage === "config") throw new Error("Injected stop after config stage");
+		completeMigration();
+		return {
+			status: "recovered",
+			importedAgents: payload.agents.list.length,
+			importedBindings: payload.bindings?.length ?? 0
+		};
+	}
+	const configBackupPath = `${options.configPath}.pre-agent-sqlite-v1.bak`;
+	if (!existsSync(configBackupPath)) copyFileSync(options.configPath, configBackupPath);
+	const database = getXopcDatabase();
+	importLegacyPayload(payload, digest, configBackupPath, database.path === ":memory:" ? null : backupDatabaseBeforeCutover(database.db, database.path, "agent-sqlite-v1"));
+	if (options.stopAfterStage === "database") throw new Error("Injected stop after database stage");
+	writeCleanConfig(options.configPath, raw);
+	if (options.stopAfterStage === "config") throw new Error("Injected stop after config stage");
+	completeMigration();
+	return {
+		status: "migrated",
+		importedAgents: payload.agents.list.length,
+		importedBindings: payload.bindings?.length ?? 0
+	};
+}
+//#endregion
+export { cutoverLegacyAgentConfig };

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

@@ -0,0 +1,39 @@
+import { type AgentDefaults, type AgentEntry } from '../agent-config/index.js';
+import { type BindingRule } from '../routing/binding-schema.js';
+import type { AgentCatalogSettings, AgentCatalogSnapshot, StoredAgent } from './types.js';
+export declare class AgentCatalogRepository {
+    ensureInitialized(defaults?: AgentDefaults): void;
+    getSettings(): AgentCatalogSettings;
+    list(options?: {
+        includeDeleted?: boolean;
+        readyOnly?: boolean;
+    }): StoredAgent[];
+    get(id: string, options?: {
+        includeDeleted?: boolean;
+    }): StoredAgent | null;
+    snapshot(): AgentCatalogSnapshot;
+    create(entryInput: AgentEntry, options?: {
+        ready?: boolean;
+    }): StoredAgent;
+    update(id: string, expectedRevision: number, entryInput: AgentEntry, options?: {
+        reprovision?: boolean;
+    }): StoredAgent;
+    setDefault(agentIdRaw: string, expectedRevision: number): AgentCatalogSettings;
+    updateDefaults(defaultsInput: AgentDefaults, expectedRevision: number): AgentCatalogSettings;
+    replaceBindings(bindingsInput: BindingRule[]): BindingRule[];
+    setSurfaceDefault(surfaceRaw: string, agentIdRaw: string): void;
+    clearSurfaceDefault(surfaceRaw: string): void;
+    markProvisioned(agentIdRaw: string): StoredAgent;
+    markProvisioningFailed(agentIdRaw: string, errorMessage: string): void;
+    listPendingProvisioningAgentIds(): string[];
+    listPendingPurgeAgentIds(): string[];
+    markPurged(agentIdRaw: string): void;
+    markPurgeFailed(agentIdRaw: string, errorMessage: string): void;
+    delete(agentIdRaw: string, options?: {
+        purge?: boolean;
+    }): {
+        agent: StoredAgent;
+        removedBindings: number;
+    };
+}
+export declare function defaultAgentDefaults(): AgentDefaults;