@xopcai/xopc 0.0.171 → 0.0.173

package/dist/src/agent/skills/marketplace/search.js

@@ -0,0 +1,193 @@
+import { searchClawHubFederatedSkills } from "./adapters/clawhub/adapter.js";
+import { listMarketplacePackages } from "../skills-marketplace.js";
+//#region src/agent/skills/marketplace/search.ts
+const SKILL_MARKETPLACE_SEARCH_SOURCES = [
+	"store",
+	"clawhub",
+	"skills-sh"
+];
+function boundedNumber(value) {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+function normalizeDate(value) {
+	if (value === void 0 || value === null || value === "") return null;
+	const numeric = typeof value === "number" ? value : typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value.trim()) ? Number(value) : null;
+	const timestamp = numeric !== null && Number.isFinite(numeric) ? Math.abs(numeric) < 0xe8d4a51000 ? numeric * 1e3 : numeric : value;
+	const date = new Date(timestamp);
+	return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function scannerStatus(value) {
+	const normalized = String(value ?? "").trim().toLowerCase();
+	if (normalized === "pass") return "pass";
+	if (normalized === "warn" || normalized === "warning" || normalized === "review") return "warn";
+	if (normalized === "fail" || normalized === "failed" || normalized === "block") return "fail";
+	return "unknown";
+}
+function securityFromClawHub(item) {
+	const scanners = Object.entries(item.trust?.upstreamScanners ?? {}).map(([name, evidence]) => ({
+		name,
+		status: scannerStatus(evidence.status),
+		checkedAt: normalizeDate(evidence.sourceCheckedAt),
+		url: evidence.sourceUrl ?? null
+	}));
+	const statuses = scanners.map((scanner) => scanner.status);
+	return {
+		status: statuses.includes("fail") ? "fail" : statuses.includes("warn") ? "warn" : statuses.length > 0 && statuses.every((value) => value === "pass") ? "pass" : scannerStatus(item.trust?.clawHubVerdict),
+		scanners
+	};
+}
+function absoluteClawHubUrl(value) {
+	if (!value) return null;
+	try {
+		const base = process.env.CLAWHUB_REGISTRY?.trim() || "https://clawhub.ai";
+		return new URL(value, base).toString();
+	} catch {
+		return null;
+	}
+}
+function relevanceScore(query, result) {
+	const terms = query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 1);
+	if (terms.length === 0) return 0;
+	const name = result.name.toLowerCase();
+	const description = result.description.toLowerCase();
+	const matched = terms.reduce((score, term) => {
+		if (name === term) return score + 3;
+		if (name.includes(term)) return score + 2;
+		if (description.includes(term)) return score + 1;
+		return score;
+	}, 0);
+	return Math.min(35, Math.round(matched / (terms.length * 3) * 35));
+}
+function valueScore(query, result) {
+	const relevance = relevanceScore(query, result);
+	const adoption = Math.min(30, Math.log10(result.downloads + 1) * 7);
+	const endorsement = Math.min(15, Math.log10(result.stars + 1) * 6);
+	const updatedMs = result.updatedAt ? Date.parse(result.updatedAt) : 0;
+	const ageDays = updatedMs > 0 ? (Date.now() - updatedMs) / 864e5 : Number.POSITIVE_INFINITY;
+	const freshness = ageDays <= 90 ? 15 : ageDays <= 365 ? 10 : ageDays <= 730 ? 5 : 0;
+	const provenance = result.canonicalUrl && result.install.reference ? 5 : 0;
+	const security = result.security.status === "pass" ? 5 : result.security.status === "warn" ? -20 : result.security.status === "fail" ? -100 : 0;
+	return Math.round((relevance + adoption + endorsement + freshness + provenance + security) * 10) / 10;
+}
+function fromClawHub(item) {
+	const source = item.source === "skills-sh" ? "skills-sh" : "clawhub";
+	const owner = item.publisher?.handle ?? item.sourceIdentity?.owner ?? item.owner?.handle ?? item.ownerHandle ?? source;
+	const reference = item.install?.reference ?? (source === "clawhub" && owner !== "clawhub" ? `${owner}/${item.slug}` : item.slug);
+	return {
+		id: item.id ?? `${source}:${reference}`,
+		provider: "clawhub",
+		source,
+		name: item.displayName || item.slug,
+		description: item.summary || "",
+		author: owner,
+		downloads: boundedNumber(item.downloads ?? item.native?.skill?.stats?.downloads),
+		stars: boundedNumber(item.native?.skill?.stats?.stars ?? item.metrics?.bookmarks),
+		updatedAt: normalizeDate(item.metrics?.updatedAt ?? item.updatedAt),
+		canonicalUrl: absoluteClawHubUrl(item.canonicalUrl ?? item.links?.canonical),
+		install: {
+			kind: item.install?.kind ?? source,
+			reference,
+			sourceUrl: item.install?.sourceUrl ?? item.links?.source ?? null
+		},
+		security: securityFromClawHub(item),
+		valueScore: 0
+	};
+}
+function dedupeAndRank(query, rows) {
+	const unique = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = `${row.source}:${row.install.reference || row.id}`.toLowerCase();
+		const scored = {
+			...row,
+			valueScore: valueScore(query, row)
+		};
+		const current = unique.get(key);
+		if (!current || scored.valueScore > current.valueScore) unique.set(key, scored);
+	}
+	return [...unique.values()].sort((a, b) => b.valueScore - a.valueScore || b.downloads - a.downloads || a.name.localeCompare(b.name));
+}
+async function searchSkillMarketplaces(params) {
+	const requested = new Set(params.sources?.length ? params.sources : SKILL_MARKETPLACE_SEARCH_SOURCES);
+	const fetchLimit = Math.min(100, Math.max(params.limit ?? 10, 20));
+	const rows = [];
+	const statuses = [];
+	const jobs = [];
+	if (requested.has("store")) jobs.push((async () => {
+		try {
+			const response = await listMarketplacePackages(params.config, {
+				q: params.query,
+				page: 1,
+				pageSize: fetchLimit,
+				sort: "downloads"
+			}, "store");
+			for (const item of response.items) rows.push({
+				id: item.id,
+				provider: "store",
+				source: "store",
+				name: item.name,
+				description: item.description,
+				author: item.author.username,
+				downloads: boundedNumber(item.downloads),
+				stars: boundedNumber(item.stars),
+				updatedAt: normalizeDate(item.updatedAt),
+				canonicalUrl: null,
+				install: {
+					kind: "store",
+					reference: item.name,
+					sourceUrl: null
+				},
+				security: {
+					status: "unknown",
+					scanners: []
+				},
+				valueScore: 0
+			});
+			statuses.push({
+				source: "store",
+				ok: true,
+				count: response.items.length
+			});
+		} catch (error) {
+			statuses.push({
+				source: "store",
+				ok: false,
+				count: 0,
+				error: String(error)
+			});
+		}
+	})());
+	if (requested.has("clawhub") || requested.has("skills-sh")) jobs.push((async () => {
+		try {
+			const converted = (await searchClawHubFederatedSkills(params.query, fetchLimit)).results.map(fromClawHub);
+			for (const source of ["clawhub", "skills-sh"]) {
+				if (!requested.has(source)) continue;
+				const matches = converted.filter((row) => row.source === source);
+				rows.push(...matches);
+				statuses.push({
+					source,
+					ok: true,
+					count: matches.length,
+					...source === "skills-sh" ? { via: "clawhub" } : {}
+				});
+			}
+		} catch (error) {
+			for (const source of ["clawhub", "skills-sh"]) if (requested.has(source)) statuses.push({
+				source,
+				ok: false,
+				count: 0,
+				error: String(error),
+				...source === "skills-sh" ? { via: "clawhub" } : {}
+			});
+		}
+	})());
+	await Promise.all(jobs);
+	const limit = Math.min(20, Math.max(1, params.limit ?? 10));
+	const orderedStatuses = SKILL_MARKETPLACE_SEARCH_SOURCES.filter((source) => requested.has(source)).map((source) => statuses.find((status) => status.source === source)).filter(Boolean);
+	return {
+		results: dedupeAndRank(params.query, rows).slice(0, limit),
+		sources: orderedStatuses
+	};
+}
+//#endregion
+export { SKILL_MARKETPLACE_SEARCH_SOURCES, searchSkillMarketplaces };

package/dist/src/agent/skills/skill-tool-gating.js

@@ -14,7 +14,8 @@ const SKILL_TOOLSET_TOOLS = {
 		"skills_list",
 		"skill_view",
 		"skill_manage"
-	]
+	],
+	skill_marketplaces: ["skills_marketplace_search"]
 };
 function emptyConditions(c) {
 	if (!c) return true;

package/dist/src/agent/tools/delegate-tool.js

@@ -28,6 +28,8 @@ const DELEGATE_BLOCKED_TOOLS = new Set([
 	"skills_list",
 	"skill_view",
 	"skill_manage",
+	"skills_marketplace_search",
+	"skill_install",
 	"bundle-mcp"
 ]);
 const DelegateTaskSchema = Type.Object({

package/dist/src/agent/tools/factory.d.ts

@@ -10,7 +10,7 @@ import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { Model, Api } from '@earendil-works/pi-ai';
 import type { Config } from '../../config/schema.js';
 import type { MessageBus } from '../../infra/bus/index.js';
-import { type SkillInstallToolOptions, type SkillInstallToolResult } from './index.js';
+import { type SkillInstallToolOptions, type SkillInstallToolResult, type MarketplaceSkillInstallToolOptions, type MarketplaceSkillInstallToolResult } from './index.js';
 import type { MemoryManager } from '../memory/manager.js';
 import type { SessionStore } from '../../session/store.js';
 import type { GatewayClarifyRequestFn } from './clarify-tool.js';
@@ -70,6 +70,8 @@ export interface ToolFactoryDeps {
     registerSkillEnvPassthrough?: (names: string[]) => void;
     /** Install managed skills from explicit sources when a capability/tool enables it. */
     installSkillFromSource?: (opts: SkillInstallToolOptions) => Promise<SkillInstallToolResult>;
+    /** Install a managed skill from a built-in marketplace provider. */
+    installSkillFromMarketplace?: (opts: MarketplaceSkillInstallToolOptions) => Promise<MarketplaceSkillInstallToolResult>;
     /** Workspace-scoped structural code intelligence runtime. */
     getCodeIntelligenceRuntime?: (workspace: string) => CodeIntelligenceRuntimeLike;
 }
@@ -86,7 +88,7 @@ export interface CreateCoreToolsOptions {
     /** Shared user memories directory used for dreaming state (`user/memories`). */
     dreamingRoot?: string;
     agentId?: string;
-    /** When set, registers `skills_list` and `skill_view` bound to this workspace\'s skills. */
+    /** When set, registers local skill tools plus marketplace discovery for this workspace. */
     getSkillManager?: () => SkillManager;
 }
 export declare class AgentToolsFactory {

package/dist/src/agent/tools/factory.js

@@ -38,6 +38,7 @@ import { createGoalTool } from "./goal-tool.js";
 import { createXopcUseTool } from "./xopc-use-tool.js";
 import { createSkillViewTool, createSkillsListTool } from "./skills-tools.js";
 import { createSkillManageTool } from "./skill-manage-tool.js";
+import { createSkillsMarketplaceSearchTool } from "./skills-marketplace-search-tool.js";
 import { createSkillInstallTool } from "./skill-install-tool.js";
 import { createToolManualTool } from "./tool-manual-tool.js";
 import { createDesktopPetTool } from "./desktop-pet-tool.js";
@@ -234,6 +235,15 @@ var AgentToolsFactory = class {
 					onSkillsFilesystemMutate: this.deps.onSkillsFilesystemMutate
 				})
 			] : [],
+			createSkillsMarketplaceSearchTool({
+				getConfig: () => this.deps.getConfig?.(),
+				getSkillManager: getSkillMgr
+			}),
+			...this.deps.installSkillFromSource || this.deps.installSkillFromMarketplace ? [createSkillInstallTool({
+				installSkillFromSource: this.deps.installSkillFromSource,
+				installSkillFromMarketplace: this.deps.installSkillFromMarketplace,
+				getSessionKey: () => this.deps.getCurrentContext()?.sessionKey
+			})] : [],
 			readTool,
 			...codeIntelligenceTools,
 			writeTool,
@@ -328,15 +338,11 @@ var AgentToolsFactory = class {
 			if (disabled?.has(toolName) || toolNames.has(toolName)) continue;
 			toolNames.add(toolName);
 			if (toolName === "create_desktop_pet") raw.push(createDesktopPetTool());
-			if (toolName === "skill_install") raw.push(createSkillInstallTool({
-				installSkillFromSource: this.deps.installSkillFromSource,
-				getSessionKey: () => this.deps.getCurrentContext()?.sessionKey
-			}));
 		}
 		return wrapToolsWithProtection(raw, this.deps.toolExecutorConfig);
 	}
 	getLazyCapabilityToolNames() {
-		return ["create_desktop_pet", ...this.deps.installSkillFromSource ? ["skill_install"] : []];
+		return ["create_desktop_pet"];
 	}
 	createAllTools(coreOptions) {
 		const coreTools = this.createCoreTools(coreOptions);

package/dist/src/agent/tools/index.d.ts

@@ -32,7 +32,8 @@ export { createGoalTool, type GoalToolOptions } from './goal-tool.js';
 export { createXopcUseTool, type XopcUseToolDeps, type XopcUseToolInput } from './xopc-use-tool.js';
 export { createSkillsListTool, createSkillViewTool, type SkillsToolsDeps } from './skills-tools.js';
 export { createSkillManageTool, type SkillManageToolDeps } from './skill-manage-tool.js';
-export { createSkillInstallTool, type SkillInstallToolDeps, type SkillInstallToolOptions, type SkillInstallToolResult, } from './skill-install-tool.js';
+export { createSkillsMarketplaceSearchTool, type SkillsMarketplaceSearchToolDeps, } from './skills-marketplace-search-tool.js';
+export { createSkillInstallTool, type SkillInstallToolDeps, type SkillInstallToolOptions, type SkillInstallToolResult, type MarketplaceSkillInstallToolOptions, type MarketplaceSkillInstallToolResult, } from './skill-install-tool.js';
 export { createToolManualTool } from './tool-manual-tool.js';
 export { createDesktopPetTool, type DesktopPetCreateDetails } from './desktop-pet-tool.js';
 export { createCodeIntelligenceTools } from '../code-intelligence/tools.js';

package/dist/src/agent/tools/index.js

@@ -36,6 +36,7 @@ import { createGoalTool } from "./goal-tool.js";
 import { createXopcUseTool } from "./xopc-use-tool.js";
 import { createSkillViewTool, createSkillsListTool } from "./skills-tools.js";
 import { createSkillManageTool } from "./skill-manage-tool.js";
+import { createSkillsMarketplaceSearchTool } from "./skills-marketplace-search-tool.js";
 import { createSkillInstallTool } from "./skill-install-tool.js";
 import { createToolManualTool } from "./tool-manual-tool.js";
 import { createDesktopPetTool } from "./desktop-pet-tool.js";
@@ -43,4 +44,4 @@ import { createCodeIntelligenceTools } from "../code-intelligence/tools.js";
 import { resolveImageModelConfigForTool } from "../image/tool-model-config.js";
 import { createImageTool } from "./image-tool.js";
 import { createImageGenerateTool, resolveImageGenerationModelConfigForTool } from "./image-generate-tool.js";
-export { BrowserManager, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, SANDBOX_ALLOWED_TOOLS, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, buildSandboxToolMap, createApplyPatchTool, createAutomationTool, createBrowserRecipeTool, createClarifyTool, createCodeIntelligenceTools, createComposioTools, createCreateShareTool, createCuratedMemoryTool, createDelegateTool, createDesktopPetTool, createDreamingTool, createExecCommandTool, createExecuteCodeTool, createFindTool, createGoalTool, createGrepTool, createImageGenerateTool, createImageTool, createListDirTool, createMemoryGetTool, createMemorySearchTool, createMessageTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };
+export { BrowserManager, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, SANDBOX_ALLOWED_TOOLS, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, buildSandboxToolMap, createApplyPatchTool, createAutomationTool, createBrowserRecipeTool, createClarifyTool, createCodeIntelligenceTools, createComposioTools, createCreateShareTool, createCuratedMemoryTool, createDelegateTool, createDesktopPetTool, createDreamingTool, createExecCommandTool, createExecuteCodeTool, createFindTool, createGoalTool, createGrepTool, createImageGenerateTool, createImageTool, createListDirTool, createMemoryGetTool, createMemorySearchTool, createMessageTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };

package/dist/src/agent/tools/skill-install-tool.d.ts

@@ -21,8 +21,25 @@ export interface SkillInstallToolResult {
     contentHash: string;
     target?: SkillInstallTarget;
 }
+export interface MarketplaceSkillInstallToolOptions {
+    provider: 'store' | 'clawhub';
+    name: string;
+    version?: string;
+    target?: SkillInstallTarget;
+    sessionKey?: string;
+    force?: boolean;
+}
+export interface MarketplaceSkillInstallToolResult {
+    skillId: string;
+    path: string;
+    provider: 'store' | 'clawhub';
+    name: string;
+    version?: string;
+    target?: SkillInstallTarget;
+}
 export interface SkillInstallToolDeps {
     installSkillFromSource?: (opts: SkillInstallToolOptions) => Promise<SkillInstallToolResult>;
+    installSkillFromMarketplace?: (opts: MarketplaceSkillInstallToolOptions) => Promise<MarketplaceSkillInstallToolResult>;
     getSessionKey?: () => string | undefined;
 }
 export declare function createSkillInstallTool(deps: SkillInstallToolDeps): AgentTool;

package/dist/src/agent/tools/skill-install-tool.js

@@ -2,11 +2,14 @@ import { isSkillInstallTarget } from "../skills/install-target.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/skill-install-tool.ts
 const SkillInstallSchema = Type.Object({
-	source: Type.String({ description: "Explicit skill source: Git URL, GitHub repository URL, https .zip/.tar.gz URL, file:// URL, or local archive/path." }),
+	source: Type.Optional(Type.String({ description: "Explicit source install: Git URL, GitHub repository URL, https .zip/.tar.gz URL, file:// URL, or local archive/path." })),
+	provider: Type.Optional(Type.Union([Type.Literal("store"), Type.Literal("clawhub")], { description: "Marketplace provider. Use with name; copy it from skills_marketplace_search." })),
+	name: Type.Optional(Type.String({ description: "Marketplace package name or install.reference. For ClawHub prefer owner/slug to disambiguate publishers." })),
+	version: Type.Optional(Type.String({ description: "Optional marketplace package version." })),
 	ref: Type.Optional(Type.String({ description: "Optional Git branch/tag/ref." })),
 	path: Type.Optional(Type.String({ description: "Optional subdirectory inside the source that contains SKILL.md." })),
-	skillId: Type.Optional(Type.String({ description: "Optional target managed skill id under the current workspace .xopc/skills." })),
-	target: Type.Optional(Type.Union([Type.Literal("workspace"), Type.Literal("global")], { description: "Install target. Defaults to workspace. Use global only when the user explicitly asks for a global/personal install." })),
+	skillId: Type.Optional(Type.String({ description: "Optional target managed skill id under the selected global or workspace skills root." })),
+	target: Type.Optional(Type.Union([Type.Literal("workspace"), Type.Literal("global")], { description: "Install target. Defaults to global (~/.xopc/skills). Use workspace only when the user explicitly asks to scope the skill to the current agent workspace." })),
 	force: Type.Optional(Type.Boolean({ description: "Replace an existing managed skill with the same id." })),
 	strictScan: Type.Optional(Type.Boolean({ description: "Fail when the current scanner reports critical findings." }))
 });
@@ -17,9 +20,70 @@ function createSkillInstallTool(deps) {
 	return {
 		name: "skill_install",
 		label: "Install skill",
-		description: "Install an xopc skill from an explicit user-provided source. Use only when the user clearly asks to install or update a skill; do not install from a URL the user merely pasted without installation intent.",
+		description: "Install an xopc skill from a Store/ClawHub marketplace result or an explicit source. Use only when the user clearly asks to install or update a skill; never treat search or a pasted URL as installation consent.",
 		parameters: SkillInstallSchema,
 		async execute(_toolCallId, params) {
+			const provider = clean(params.provider);
+			const name = clean(params.name);
+			const target = isSkillInstallTarget(params.target) ? params.target : "global";
+			const sessionKey = deps.getSessionKey?.();
+			if (provider || name) {
+				if (provider !== "store" && provider !== "clawhub") return {
+					content: [{
+						type: "text",
+						text: "Marketplace installs require provider: store or clawhub."
+					}],
+					details: { errorCode: "missing_provider" }
+				};
+				if (!name) return {
+					content: [{
+						type: "text",
+						text: "Marketplace installs require name from the search result."
+					}],
+					details: { errorCode: "missing_name" }
+				};
+				if (!deps.installSkillFromMarketplace) return {
+					content: [{
+						type: "text",
+						text: "Marketplace skill installation is not available in this runtime context."
+					}],
+					details: { errorCode: "marketplace_install_unavailable" }
+				};
+				try {
+					const result = await deps.installSkillFromMarketplace({
+						provider,
+						name,
+						version: clean(params.version),
+						target,
+						sessionKey,
+						force: params.force === true
+					});
+					return {
+						content: [{
+							type: "text",
+							text: [
+								`Installed skill "${result.skillId}" from ${result.provider}.`,
+								`Package: ${result.name}${result.version ? `@${result.version}` : ""}`,
+								`Target: ${result.target ?? target}`,
+								`Path: ${result.path}`
+							].join("\n")
+						}],
+						details: { result }
+					};
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					return {
+						content: [{
+							type: "text",
+							text: `Marketplace skill install failed: ${message}`
+						}],
+						details: {
+							errorCode: "install_failed",
+							errorMessage: message
+						}
+					};
+				}
+			}
 			if (!deps.installSkillFromSource) return {
 				content: [{
 					type: "text",
@@ -41,8 +105,8 @@ function createSkillInstallTool(deps) {
 					ref: clean(params.ref),
 					path: clean(params.path),
 					skillId: clean(params.skillId),
-					target: isSkillInstallTarget(params.target) ? params.target : void 0,
-					sessionKey: deps.getSessionKey?.(),
+					target,
+					sessionKey,
 					force: params.force === true,
 					strictScan: params.strictScan === true
 				});
@@ -51,7 +115,7 @@ function createSkillInstallTool(deps) {
 						type: "text",
 						text: [
 							`Installed skill "${result.skillId}".`,
-							`Target: ${result.target ?? "workspace"}`,
+							`Target: ${result.target ?? target}`,
 							`Source: ${result.source} (${result.kind})`,
 							`Path: ${result.path}`,
 							`Tree hash: ${result.contentHash.slice(0, 16)}`
@@ -72,7 +136,11 @@ function createSkillInstallTool(deps) {
 					}
 				};
 			}
-		}
+		},
+		mutatesWorkspace: true,
+		mutationScope: "unknown",
+		idempotent: false,
+		finalGuardRelevant: true
 	};
 }
 //#endregion

package/dist/src/agent/tools/skills-marketplace-search-tool.d.ts

@@ -0,0 +1,17 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.js';
+import type { SkillManager } from '../skills/skill-manager.js';
+import { searchSkillMarketplaces, type SkillsMarketplaceSearchSource } from '../skills/marketplace/search.js';
+type SearchResponse = Awaited<ReturnType<typeof searchSkillMarketplaces>>;
+export interface SkillsMarketplaceSearchToolDeps {
+    getConfig: () => Config | undefined;
+    getSkillManager?: () => SkillManager | undefined;
+    search?: (params: {
+        config: Config;
+        query: string;
+        sources?: SkillsMarketplaceSearchSource[];
+        limit?: number;
+    }) => Promise<SearchResponse>;
+}
+export declare function createSkillsMarketplaceSearchTool(deps: SkillsMarketplaceSearchToolDeps): AgentTool;
+export {};

package/dist/src/agent/tools/skills-marketplace-search-tool.js

@@ -0,0 +1,77 @@
+import { searchSkillMarketplaces } from "../skills/marketplace/search.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/skills-marketplace-search-tool.ts
+const SkillsMarketplaceSearchSchema = Type.Object({
+	query: Type.String({
+		minLength: 2,
+		description: "Capability or task to search for, using concise English keywords when possible"
+	}),
+	sources: Type.Optional(Type.Array(Type.Union([
+		Type.Literal("store"),
+		Type.Literal("clawhub"),
+		Type.Literal("skills-sh")
+	]), {
+		minItems: 1,
+		maxItems: 3,
+		uniqueItems: true
+	})),
+	limit: Type.Optional(Type.Integer({
+		minimum: 1,
+		maximum: 20,
+		default: 10
+	}))
+});
+function jsonResult(payload) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(payload, null, 2)
+		}],
+		details: {}
+	};
+}
+function createSkillsMarketplaceSearchTool(deps) {
+	return {
+		name: "skills_marketplace_search",
+		label: "🔎 Find skills",
+		description: "Search the XOPC Store, native ClawHub catalog, and skills.sh results federated by ClawHub. Returns normalized provenance, install references, adoption metrics, partial-source errors, and a heuristic value score. Read-only; never installs a skill.",
+		parameters: SkillsMarketplaceSearchSchema,
+		mutatesWorkspace: false,
+		mutationScope: "none",
+		supportsParallel: true,
+		idempotent: true,
+		async execute(_toolCallId, params) {
+			const config = deps.getConfig();
+			if (!config) return jsonResult({
+				success: false,
+				error: "XOPC config is not available in this runtime context."
+			});
+			const query = params.query.trim();
+			if (query.length < 2) return jsonResult({
+				success: false,
+				error: "query must contain at least 2 characters."
+			});
+			const response = await (deps.search ?? searchSkillMarketplaces)({
+				config,
+				query,
+				sources: params.sources,
+				limit: params.limit
+			});
+			const manager = deps.getSkillManager?.();
+			const results = response.results.map((result) => ({
+				...result,
+				installed: Boolean(manager?.findSkill(result.name))
+			}));
+			return jsonResult({
+				success: true,
+				query,
+				scoreIsHeuristic: true,
+				sources: response.sources,
+				results,
+				installationRequiresConfirmation: true
+			});
+		}
+	};
+}
+//#endregion
+export { createSkillsMarketplaceSearchTool };

package/dist/src/automations/domain/validation.d.ts

@@ -90,12 +90,12 @@ export declare const AutomationStateSchema: z.ZodObject<{
     runningRunId: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     lastRunAtMs: z.ZodOptional<z.ZodNumber>;
     lastRunStatus: z.ZodOptional<z.ZodEnum<{
+        queued: "queued";
+        running: "running";
         failed: "failed";
         cancelled: "cancelled";
         timeout: "timeout";
         succeeded: "succeeded";
-        running: "running";
-        queued: "queued";
     }>>;
     lastError: z.ZodOptional<z.ZodString>;
     consecutiveFailures: z.ZodOptional<z.ZodNumber>;
@@ -185,12 +185,12 @@ export declare const AutomationSchema: z.ZodObject<{
         runningRunId: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
         lastRunAtMs: z.ZodOptional<z.ZodNumber>;
         lastRunStatus: z.ZodOptional<z.ZodEnum<{
+            queued: "queued";
+            running: "running";
             failed: "failed";
             cancelled: "cancelled";
             timeout: "timeout";
             succeeded: "succeeded";
-            running: "running";
-            queued: "queued";
         }>>;
         lastError: z.ZodOptional<z.ZodString>;
         consecutiveFailures: z.ZodOptional<z.ZodNumber>;
@@ -283,12 +283,12 @@ export declare const CreateAutomationSchema: z.ZodObject<{
         runningRunId: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
         lastRunAtMs: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
         lastRunStatus: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            queued: "queued";
+            running: "running";
             failed: "failed";
             cancelled: "cancelled";
             timeout: "timeout";
             succeeded: "succeeded";
-            running: "running";
-            queued: "queued";
         }>>>;
         lastError: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         consecutiveFailures: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
@@ -331,12 +331,12 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
         runningRunId: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
         lastRunAtMs: z.ZodOptional<z.ZodNumber>;
         lastRunStatus: z.ZodOptional<z.ZodEnum<{
+            queued: "queued";
+            running: "running";
             failed: "failed";
             cancelled: "cancelled";
             timeout: "timeout";
             succeeded: "succeeded";
-            running: "running";
-            queued: "queued";
         }>>;
         lastError: z.ZodOptional<z.ZodString>;
         consecutiveFailures: z.ZodOptional<z.ZodNumber>;

package/dist/src/automations/draft/automation-draft-validator.d.ts

@@ -89,7 +89,7 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
             nextRunAtMs?: number;
             runningRunId?: string;
             lastRunAtMs?: number;
-            lastRunStatus?: "failed" | "cancelled" | "timeout" | "succeeded" | "running" | "queued";
+            lastRunStatus?: "queued" | "running" | "failed" | "cancelled" | "timeout" | "succeeded";
             lastError?: string;
             consecutiveFailures?: number;
         };

package/dist/src/browser/providers/cloakbrowser.js

@@ -11,8 +11,8 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdir, mkdtemp, rm, stat } from "node:fs/promises";
-import { Readable, Transform } from "node:stream";
 import AdmZip from "adm-zip";
+import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 //#region src/browser/providers/cloakbrowser.ts
 /**

package/dist/src/capabilities/store-connector.js

@@ -1,5 +1,5 @@
-import { installConnectorDefinition } from "../connectors/install.js";
 import { downloadConnectorStoreZipBuffer, fetchStoreConnectorPackageDetail, listConnectorPackages, resolveSkillsStoreBaseUrl } from "../agent/skills/marketplace/adapters/store/store-api-client.js";
+import { installConnectorDefinition } from "../connectors/install.js";
 import { createHash } from "node:crypto";
 import { isIP } from "node:net";
 import AdmZip from "adm-zip";

package/dist/src/cli/commands/doctor/checks/database-schema.js

@@ -52,7 +52,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${status.dbVersion} (current release v61).`,
+		message: `SQLite schema v${status.dbVersion} (current release v65).`,
 		hints: []
 	};
 }