@clawhive/openclaw-plugin 0.2.0

package/dist/src/market-install/executor.js

@@ -0,0 +1,352 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ClawHiveApiError } from "../client.js";
+import { addInstallBreadcrumb, captureInstallFailure, } from "../telemetry.js";
+/**
+ * Compare dotted versions without pulling in a full semver dependency.
+ */
+export function compareLooseVersions(current, minimum) {
+    const currentParts = current.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const minimumParts = minimum.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const maxLength = Math.max(currentParts.length, minimumParts.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const left = currentParts[index] ?? 0;
+        const right = minimumParts[index] ?? 0;
+        if (left > right) {
+            return 1;
+        }
+        if (left < right) {
+            return -1;
+        }
+    }
+    return 0;
+}
+/**
+ * Build a stable error instance so durable install failures and telemetry match.
+ */
+function createInstallFailure(reasonKind, errorMessage, details = {}, status = "failed") {
+    return {
+        reasonKind,
+        errorMessage,
+        details,
+        status,
+    };
+}
+function buildInstallDetails(job, input = {}) {
+    return {
+        listingId: job.listingId,
+        releaseId: job.releaseId,
+        sourceRef: job.sourceRef,
+        sourceType: job.sourceType,
+        fingerprint: job.fingerprint,
+        targetNodeId: job.targetNodeId,
+        targetNodeName: job.targetNodeName,
+        version: job.version,
+        ...input,
+    };
+}
+function formatInstallError(error) {
+    if (error instanceof ClawHiveApiError) {
+        return `${error.message} (status=${error.status})`;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function extractAgencySourcePath(sourceRef) {
+    if (!sourceRef?.trim()) {
+        return undefined;
+    }
+    const marker = ":integrations/";
+    const markerIndex = sourceRef.indexOf(marker);
+    return markerIndex >= 0
+        ? sourceRef.slice(markerIndex + 1)
+        : undefined;
+}
+function ensureWorkspaceRelativePath(relativePath) {
+    const normalized = path.posix.normalize(relativePath.trim().replaceAll("\\", "/"));
+    if (!normalized || normalized === "." || normalized.startsWith("../") || normalized.startsWith("/")) {
+        throw new Error(`Workspace file path must stay inside the agent workspace: ${relativePath}`);
+    }
+    return normalized;
+}
+function isWithinDirectory(parentDir, targetPath) {
+    const relative = path.relative(parentDir, targetPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function resolveManifestAgentId(job, manifest) {
+    const explicitId = manifest.agent.id?.trim();
+    if (explicitId) {
+        return explicitId;
+    }
+    if (job.listingId?.trim()) {
+        return job.listingId.trim();
+    }
+    return job.releaseId;
+}
+/**
+ * Confirm the fetched manifest still matches the immutable release that the job claimed.
+ */
+function validateFetchedManifest(job, manifest) {
+    if (manifest.release.releaseId !== job.releaseId) {
+        return createInstallFailure("artifact_fetch_failed", `The fetched manifest points at release ${manifest.release.releaseId}, but the claimed job expects ${job.releaseId}.`, buildInstallDetails(job, {
+            manifestReleaseId: manifest.release.releaseId,
+        }));
+    }
+    if (job.fingerprint?.trim() &&
+        manifest.release.fingerprint?.trim() &&
+        job.fingerprint.trim() !== manifest.release.fingerprint.trim()) {
+        return createInstallFailure("artifact_fetch_failed", "The fetched manifest fingerprint does not match the claimed release fingerprint.", buildInstallDetails(job, {
+            manifestFingerprint: manifest.release.fingerprint,
+        }));
+    }
+    if (job.sourceRef?.trim() &&
+        manifest.release.sourceRef?.trim() &&
+        job.sourceRef.trim() !== manifest.release.sourceRef.trim()) {
+        return createInstallFailure("artifact_fetch_failed", "The fetched manifest source reference does not match the claimed release pin.", buildInstallDetails(job, {
+            manifestSourceRef: manifest.release.sourceRef,
+        }));
+    }
+    return null;
+}
+function upsertInstalledAgentConfig(currentConfig, manifest, agentId) {
+    const agentsSection = currentConfig.agents;
+    const existingList = Array.isArray(agentsSection?.list)
+        ? [...agentsSection.list]
+        : [];
+    const existingEntry = existingList.find((entry) => entry?.id === agentId);
+    const explicitEntry = asRecord(manifest.agent.entry) ?? {};
+    const nextEntry = {
+        ...(existingEntry ?? {}),
+        id: agentId,
+        name: manifest.agent.name.trim(),
+    };
+    const provenance = manifest.release.sourceType === "agency-github"
+        ? {
+            agentId,
+            repo: "msitarzewski/agency-agents",
+            sourcePath: typeof explicitEntry.sourcePath === "string"
+                ? explicitEntry.sourcePath
+                : extractAgencySourcePath(manifest.release.sourceRef),
+            sourceRef: manifest.release.sourceRef,
+            sourceType: manifest.release.sourceType,
+        }
+        : undefined;
+    const filteredList = existingList.filter((entry) => entry?.id !== agentId);
+    filteredList.push(nextEntry);
+    return {
+        nextConfig: {
+            ...currentConfig,
+            agents: {
+                ...(agentsSection ?? {}),
+                list: filteredList,
+            },
+        },
+        nextEntry,
+        provenance,
+    };
+}
+/**
+ * Materialize the approved manifest into local workspace files and an OpenClaw agent entry.
+ */
+async function applyManifestToLocalAgent(job, manifest, options) {
+    const currentConfig = options.pluginApi.runtime.config.loadConfig();
+    const agentId = resolveManifestAgentId(job, manifest);
+    const { nextConfig, nextEntry, provenance } = upsertInstalledAgentConfig(currentConfig, manifest, agentId);
+    const workspaceDir = options.pluginApi.runtime.agent.resolveAgentWorkspaceDir(nextConfig, agentId);
+    await options.pluginApi.runtime.agent.ensureAgentWorkspace({
+        dir: workspaceDir,
+        ensureBootstrapFiles: true,
+    });
+    const workspaceFiles = manifest.agent.workspaceFiles ?? [];
+    for (const workspaceFile of workspaceFiles) {
+        const relativePath = ensureWorkspaceRelativePath(workspaceFile.path);
+        const targetPath = path.resolve(workspaceDir, relativePath);
+        if (!isWithinDirectory(workspaceDir, targetPath)) {
+            throw new Error(`Workspace file escapes the target directory: ${workspaceFile.path}`);
+        }
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, workspaceFile.content, "utf8");
+    }
+    await options.pluginApi.runtime.config.writeConfigFile(nextConfig);
+    try {
+        const syncResult = await options.api.syncAgents([{
+                openclawAgentId: agentId,
+                name: nextEntry.name?.trim() || agentId,
+                description: manifest.agent.description ?? null,
+                avatarUrl: manifest.agent.avatarUrl ?? null,
+                config: {
+                    agency: provenance,
+                    workspace: nextEntry.workspace,
+                    agentDir: nextEntry.agentDir,
+                },
+            }]);
+        options.onAgentsSynced?.(syncResult.items);
+    }
+    catch (error) {
+        options.logger.warn(`ClawHive installed agent ${agentId} locally but failed to sync it to cloud immediately: ${formatInstallError(error)}`);
+    }
+    return {
+        agentId,
+        workspaceDir,
+        workspaceFileCount: workspaceFiles.length,
+    };
+}
+async function failInstallJob(job, failure, options) {
+    options.onStageChange?.(failure.status === "cancelled" ? "cancelled" : "failed");
+    addInstallBreadcrumb({
+        stage: failure.status === "cancelled" ? "cancelled" : "failed",
+        job,
+        reasonKind: failure.reasonKind,
+        data: failure.details,
+    });
+    captureInstallFailure({
+        error: new Error(failure.errorMessage),
+        reasonKind: failure.reasonKind,
+        job,
+    });
+    await options.api.updateInstallJob({
+        pluginNodeId: options.pluginNodeId,
+        jobId: job.jobId,
+        userId: options.userId,
+        status: failure.status === "cancelled" ? "cancelled" : "failed",
+        reasonKind: failure.reasonKind,
+        errorMessage: failure.errorMessage,
+        details: buildInstallDetails(job, failure.details),
+    });
+}
+/**
+ * Execute one claimed install job and always durably report the final result.
+ */
+export async function executeInstallJob(job, options) {
+    addInstallBreadcrumb({
+        stage: "claimed",
+        job,
+    });
+    if (job.targetNodeId !== options.pluginNodeId) {
+        await failInstallJob(job, createInstallFailure("claim_rejected", "The claimed install job targets a different OpenClaw node.", buildInstallDetails(job, {
+            expectedTargetNodeId: options.pluginNodeId,
+        })), options);
+        return;
+    }
+    const requireClaimedArtifact = options.requireClaimedArtifact ?? true;
+    if (requireClaimedArtifact && !job.version?.trim()) {
+        await failInstallJob(job, createInstallFailure("claim_rejected", "The install job is missing the approved release version."), options);
+        return;
+    }
+    if (job.minPluginVersion &&
+        compareLooseVersions(options.pluginVersion, job.minPluginVersion) < 0) {
+        await failInstallJob(job, createInstallFailure("compatibility_rejected", `This node runs plugin ${options.pluginVersion}, but the release requires plugin ${job.minPluginVersion} or newer.`, buildInstallDetails(job, {
+            currentPluginVersion: options.pluginVersion,
+            minPluginVersion: job.minPluginVersion,
+        })), options);
+        return;
+    }
+    if (job.minOpenClawVersion && !options.openClawVersion) {
+        await failInstallJob(job, createInstallFailure("compatibility_rejected", `This release requires OpenClaw ${job.minOpenClawVersion} or newer, but the host version could not be determined.`, buildInstallDetails(job, {
+            minOpenClawVersion: job.minOpenClawVersion,
+        })), options);
+        return;
+    }
+    if (job.minOpenClawVersion &&
+        options.openClawVersion &&
+        compareLooseVersions(options.openClawVersion, job.minOpenClawVersion) < 0) {
+        await failInstallJob(job, createInstallFailure("compatibility_rejected", `This node runs OpenClaw ${options.openClawVersion}, but the release requires OpenClaw ${job.minOpenClawVersion} or newer.`, buildInstallDetails(job, {
+            currentOpenClawVersion: options.openClawVersion,
+            minOpenClawVersion: job.minOpenClawVersion,
+        })), options);
+        return;
+    }
+    if (!job.sourceRef?.trim() ||
+        (requireClaimedArtifact && !job.fingerprint?.trim())) {
+        await failInstallJob(job, createInstallFailure("artifact_fetch_failed", requireClaimedArtifact
+            ? "The claimed release is missing publishSourceRef or publishFingerprint, so the plugin cannot verify the approved artifact."
+            : "The claimed release is missing publishSourceRef, so the plugin cannot fetch the approved artifact.", buildInstallDetails(job)), options);
+        return;
+    }
+    options.onStageChange?.("installing");
+    addInstallBreadcrumb({
+        stage: "installing",
+        job,
+        data: {
+            compatibilityNotes: job.compatibilityNotes,
+            currentOpenClawVersion: options.openClawVersion,
+            currentPluginVersion: options.pluginVersion,
+        },
+    });
+    await options.api.updateInstallJob({
+        pluginNodeId: options.pluginNodeId,
+        jobId: job.jobId,
+        userId: options.userId,
+        status: "installing",
+        details: buildInstallDetails(job, {
+            compatibilityNotes: job.compatibilityNotes,
+            currentOpenClawVersion: options.openClawVersion,
+            currentPluginVersion: options.pluginVersion,
+        }),
+    });
+    let manifest;
+    try {
+        const result = await options.api.fetchInstallManifest({
+            pluginNodeId: options.pluginNodeId,
+            jobId: job.jobId,
+            userId: options.userId,
+        });
+        manifest = result.manifest;
+    }
+    catch (error) {
+        await failInstallJob(job, createInstallFailure("artifact_fetch_failed", `Failed to fetch the approved install manifest: ${formatInstallError(error)}`, buildInstallDetails(job, {
+            currentOpenClawVersion: options.openClawVersion,
+            currentPluginVersion: options.pluginVersion,
+        })), options);
+        return;
+    }
+    const manifestFailure = validateFetchedManifest(job, manifest);
+    if (manifestFailure) {
+        await failInstallJob(job, manifestFailure, options);
+        return;
+    }
+    let applyResult;
+    try {
+        applyResult = await applyManifestToLocalAgent(job, manifest, options);
+    }
+    catch (error) {
+        await failInstallJob(job, createInstallFailure("install_apply_failed", `Failed to apply the approved manifest locally: ${formatInstallError(error)}`, buildInstallDetails(job, {
+            agentId: resolveManifestAgentId(job, manifest),
+            currentOpenClawVersion: options.openClawVersion,
+            currentPluginVersion: options.pluginVersion,
+            workspaceFiles: (manifest.agent.workspaceFiles ?? []).map((file) => file.path),
+        })), options);
+        return;
+    }
+    options.onStageChange?.("succeeded");
+    addInstallBreadcrumb({
+        stage: "succeeded",
+        job,
+        data: {
+            agentId: applyResult.agentId,
+            workspaceDir: applyResult.workspaceDir,
+            workspaceFileCount: applyResult.workspaceFileCount,
+        },
+    });
+    options.logger.info(`ClawHive installed market release ${job.releaseId} as local agent ${applyResult.agentId}.`);
+    await options.api.updateInstallJob({
+        pluginNodeId: options.pluginNodeId,
+        jobId: job.jobId,
+        userId: options.userId,
+        status: "succeeded",
+        details: buildInstallDetails(job, {
+            agentId: applyResult.agentId,
+            workspaceDir: applyResult.workspaceDir,
+            workspaceFileCount: applyResult.workspaceFileCount,
+            manifestSourceRef: manifest.release.sourceRef,
+            manifestFingerprint: manifest.release.fingerprint,
+        }),
+    });
+}

package/dist/src/market-install/types.d.ts

@@ -0,0 +1,62 @@
+export type MarketInstallUpdateStatus = "installing" | "succeeded" | "failed" | "cancelled";
+export type MarketInstallReasonKind = "claim_rejected" | "artifact_fetch_failed" | "compatibility_rejected" | "install_apply_failed" | "cancelled";
+export type MarketInstallClaimedJob = {
+    jobId: string;
+    listingId: string | null;
+    listingName: string | null;
+    releaseId: string;
+    version: string | null;
+    sourceRef: string | null;
+    sourceType: string | null;
+    fingerprint: string | null;
+    minPluginVersion: string | null;
+    minOpenClawVersion: string | null;
+    compatibilityNotes: string | null;
+    targetNodeId: string | null;
+    targetNodeName: string | null;
+    status: "dispatched";
+    reasonKind: string | null;
+    failureReason: string | null;
+    createdAt: string | null;
+    updatedAt: string;
+};
+export type ActiveInstallStage = "claimed" | "installing" | "succeeded" | "failed" | "cancelled";
+export type ActiveInstallJobState = {
+    jobId: string;
+    listingId: string | null;
+    listingName: string | null;
+    releaseId: string;
+    version: string | null;
+    targetNodeId: string | null;
+    targetNodeName: string | null;
+    stage: ActiveInstallStage;
+    updatedAt: string;
+};
+export type InstallExecutionFailure = {
+    reasonKind: MarketInstallReasonKind;
+    errorMessage: string;
+    details?: Record<string, unknown>;
+    status?: Extract<MarketInstallUpdateStatus, "failed" | "cancelled">;
+};
+export type MarketInstallWorkspaceFile = {
+    path: string;
+    content: string;
+};
+export type MarketInstallAgentManifest = {
+    agent: {
+        id?: string | null;
+        name: string;
+        description?: string | null;
+        avatarUrl?: string | null;
+        entry?: Record<string, unknown>;
+        workspaceFiles?: MarketInstallWorkspaceFile[];
+    };
+    release: {
+        releaseId: string;
+        listingId: string | null;
+        version: string | null;
+        fingerprint: string | null;
+        sourceRef: string | null;
+        sourceType: string | null;
+    };
+};

package/dist/src/market-install/types.js

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

package/dist/src/market-install/verifier.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Error thrown when package integrity verification fails.
+ */
+export declare class PackageIntegrityError extends Error {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
+/**
+ * Compute SHA-256 hash of a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Promise resolving to hex-encoded SHA-256 hash
+ */
+export declare function computeFileSha256(filePath: string): Promise<string>;
+/**
+ * Verify package integrity by comparing computed SHA-256 against expected fingerprint.
+ *
+ * @param filePath - Absolute path to the downloaded package
+ * @param expectedFingerprint - Expected SHA-256 hash from market_releases.fingerprint
+ * @throws {PackageIntegrityError} If computed hash does not match expected fingerprint
+ */
+export declare function verifyPackageIntegrity(filePath: string, expectedFingerprint: string): Promise<void>;
+/**
+ * Assert package integrity and throw clear error on mismatch.
+ * Alias for verifyPackageIntegrity with more explicit naming.
+ *
+ * @param filePath - Absolute path to the downloaded package
+ * @param expectedFingerprint - Expected SHA-256 hash from market_releases.fingerprint
+ * @throws {PackageIntegrityError} If computed hash does not match expected fingerprint
+ */
+export declare function assertPackageIntegrity(filePath: string, expectedFingerprint: string): Promise<void>;

package/dist/src/market-install/verifier.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+/**
+ * Error thrown when package integrity verification fails.
+ */
+export class PackageIntegrityError extends Error {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(`Package integrity check failed: expected SHA-256 ${expected}, got ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "PackageIntegrityError";
+    }
+}
+/**
+ * Compute SHA-256 hash of a file.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Promise resolving to hex-encoded SHA-256 hash
+ */
+export async function computeFileSha256(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => {
+            hash.update(chunk);
+        });
+        stream.on("end", () => {
+            resolve(hash.digest("hex"));
+        });
+        stream.on("error", (error) => {
+            reject(new Error(`Failed to compute SHA-256 for ${filePath}: ${error.message}`));
+        });
+    });
+}
+/**
+ * Verify package integrity by comparing computed SHA-256 against expected fingerprint.
+ *
+ * @param filePath - Absolute path to the downloaded package
+ * @param expectedFingerprint - Expected SHA-256 hash from market_releases.fingerprint
+ * @throws {PackageIntegrityError} If computed hash does not match expected fingerprint
+ */
+export async function verifyPackageIntegrity(filePath, expectedFingerprint) {
+    const actualHash = await computeFileSha256(filePath);
+    if (actualHash !== expectedFingerprint) {
+        throw new PackageIntegrityError(expectedFingerprint, actualHash);
+    }
+}
+/**
+ * Assert package integrity and throw clear error on mismatch.
+ * Alias for verifyPackageIntegrity with more explicit naming.
+ *
+ * @param filePath - Absolute path to the downloaded package
+ * @param expectedFingerprint - Expected SHA-256 hash from market_releases.fingerprint
+ * @throws {PackageIntegrityError} If computed hash does not match expected fingerprint
+ */
+export async function assertPackageIntegrity(filePath, expectedFingerprint) {
+    await verifyPackageIntegrity(filePath, expectedFingerprint);
+}

package/dist/src/market-publish/packager.d.ts

@@ -0,0 +1,34 @@
+export type PackageResult = {
+    buffer: Buffer;
+    sizeBytes: number;
+    fingerprint: string;
+};
+export type PackageOptions = {
+    agentDir: string;
+    manifestPath?: string;
+};
+export declare class AgentManifestNotFoundError extends Error {
+    constructor(agentDir: string);
+}
+export declare class PackageTooLargeError extends Error {
+    constructor(sizeBytes: number, limitBytes: number);
+}
+export declare class PackagingError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Packages an agent directory into a tar.gz archive.
+ *
+ * Per D-01, D-02, D-03, D-04:
+ * - Format: tar.gz (standard Unix archive with gzip compression)
+ * - Contents: manifest (openclaw.agent.json) + definition files only
+ * - Manifest: embedded at tar.gz root
+ * - Fingerprint: SHA-256 over the tar.gz byte stream
+ *
+ * @param options - Packaging options
+ * @returns Package result with buffer, size, and fingerprint
+ * @throws {AgentManifestNotFoundError} if openclaw.agent.json is missing
+ * @throws {PackageTooLargeError} if package exceeds 10 MiB limit
+ * @throws {PackagingError} if tar operation fails
+ */
+export declare function packageAgentDirectory(options: PackageOptions): Promise<PackageResult>;