@clawhive/openclaw-plugin 0.2.0

package/dist/src/market-publish/packager.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { create as createTar } from "tar";
+export class AgentManifestNotFoundError extends Error {
+    constructor(agentDir) {
+        super(`Agent manifest (openclaw.agent.json) not found in ${agentDir}`);
+        this.name = "AgentManifestNotFoundError";
+    }
+}
+export class PackageTooLargeError extends Error {
+    constructor(sizeBytes, limitBytes) {
+        super(`Package size ${sizeBytes} bytes exceeds limit of ${limitBytes} bytes (${(limitBytes / 1024 / 1024).toFixed(1)} MiB)`);
+        this.name = "PackageTooLargeError";
+    }
+}
+export class PackagingError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "PackagingError";
+        if (cause instanceof Error) {
+            this.cause = cause;
+        }
+    }
+}
+const MAX_PACKAGE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MiB
+/**
+ * Determines if a file should be included in the agent package.
+ * Uses a strict whitelist approach per D-02: only manifest and definition files.
+ */
+function shouldInclude(path) {
+    const normalized = path.replace(/\\/g, "/");
+    // Always include manifest
+    if (normalized === "openclaw.agent.json") {
+        return true;
+    }
+    // Include common definition directories
+    if (normalized.startsWith("prompts/") ||
+        normalized.startsWith("tools/") ||
+        normalized.startsWith("knowledge/") ||
+        normalized.startsWith("definitions/")) {
+        return true;
+    }
+    // Include common definition file extensions
+    const allowedExtensions = [
+        ".md",
+        ".txt",
+        ".json",
+        ".yaml",
+        ".yml",
+        ".py",
+        ".js",
+        ".ts",
+    ];
+    if (allowedExtensions.some((ext) => normalized.endsWith(ext))) {
+        return true;
+    }
+    // Exclude everything else
+    return false;
+}
+/**
+ * Determines if a file should be excluded from the agent package.
+ * Blacklist for common unwanted files and directories.
+ */
+function shouldExclude(path) {
+    const normalized = path.replace(/\\/g, "/");
+    // Exclude build/runtime artifacts
+    if (normalized.includes("node_modules/") ||
+        normalized.includes(".git/") ||
+        normalized.includes("__pycache__/") ||
+        normalized.includes("dist/") ||
+        normalized.includes("build/")) {
+        return true;
+    }
+    // Exclude specific files
+    if (normalized.endsWith(".log") ||
+        normalized.endsWith(".pyc") ||
+        normalized === ".DS_Store" ||
+        normalized === "package.json" ||
+        normalized === "package-lock.json" ||
+        normalized === "tsconfig.json") {
+        return true;
+    }
+    // Apply whitelist - if not included, exclude
+    return !shouldInclude(normalized);
+}
+/**
+ * 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 async function packageAgentDirectory(options) {
+    const { agentDir, manifestPath = "openclaw.agent.json" } = options;
+    // Verify manifest exists
+    const manifestFullPath = join(agentDir, manifestPath);
+    if (!existsSync(manifestFullPath)) {
+        throw new AgentManifestNotFoundError(agentDir);
+    }
+    try {
+        // Collect all files to include
+        const filesToInclude = [];
+        await collectFiles(agentDir, "", filesToInclude);
+        // Create tar.gz in memory
+        const chunks = [];
+        const tarStream = createTar({
+            gzip: true,
+            cwd: agentDir,
+            filter: (path) => !shouldExclude(path),
+        }, filesToInclude);
+        for await (const chunk of tarStream) {
+            chunks.push(Buffer.from(chunk));
+        }
+        const buffer = Buffer.concat(chunks);
+        const sizeBytes = buffer.length;
+        // Check size limit (client-side fast fail)
+        if (sizeBytes > MAX_PACKAGE_SIZE_BYTES) {
+            throw new PackageTooLargeError(sizeBytes, MAX_PACKAGE_SIZE_BYTES);
+        }
+        // Compute SHA-256 fingerprint
+        const hash = createHash("sha256");
+        hash.update(buffer);
+        const fingerprint = hash.digest("hex");
+        return {
+            buffer,
+            sizeBytes,
+            fingerprint,
+        };
+    }
+    catch (error) {
+        if (error instanceof AgentManifestNotFoundError ||
+            error instanceof PackageTooLargeError) {
+            throw error;
+        }
+        throw new PackagingError(`Failed to package agent directory: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}
+/**
+ * Recursively collects files from a directory that should be included in the package.
+ */
+async function collectFiles(baseDir, relativeDir, result) {
+    const fullDir = join(baseDir, relativeDir);
+    const entries = await readdir(fullDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relativePath = relativeDir
+            ? join(relativeDir, entry.name)
+            : entry.name;
+        if (shouldExclude(relativePath)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await collectFiles(baseDir, relativePath, result);
+        }
+        else if (entry.isFile()) {
+            result.push(relativePath);
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+import { ClawHiveCloudApi } from "../client.js";
+import type { ClawHiveResolvedAccount } from "../config.js";
+import { packageAgentDirectory } from "./packager.js";
+export type AgentManifest = {
+    name?: string;
+    displayName?: string;
+    version?: string;
+    description?: string;
+    summary?: string;
+    author?: {
+        name?: string;
+    };
+    compatibility?: {
+        minOpenClawVersion?: string;
+        minPluginVersion?: string;
+    };
+    metadata?: {
+        category?: string;
+        tags?: string[];
+        license?: string;
+    };
+};
+export type PublishAgentInfo = {
+    name: string;
+    path: string;
+    manifest: AgentManifest;
+};
+export type PublishDefaults = {
+    name: string;
+    slug: string;
+    summary: string | undefined;
+    authorDisplayName: string | undefined;
+    category: string | undefined;
+    license: string | undefined;
+    tags: string[];
+    version: string;
+    sourceRef: string;
+    minOpenClawVersion: string | undefined;
+    minPluginVersion: string | undefined;
+};
+export type PublishOverrides = Partial<PublishDefaults> & {
+    listingId?: string;
+};
+export type PublishFlowResult = {
+    listingId: string;
+    releaseId: string | null;
+    version: string;
+    storagePath: string;
+    fingerprint: string;
+    listing: Record<string, unknown>;
+    release: Record<string, unknown>;
+};
+export declare function slugifyForListing(value: string): string;
+export declare function inferPublishDefaults(input: {
+    folderName: string;
+    manifest: AgentManifest;
+    sourceRef: string;
+    account?: Pick<ClawHiveResolvedAccount, "minOpenClawVersion" | "minPluginVersion">;
+}): PublishDefaults;
+export declare function runPublishFlow(input: {
+    agent: PublishAgentInfo;
+    account: ClawHiveResolvedAccount;
+    sourceRef: string;
+    overrides: PublishOverrides;
+    onProgress?: (uploaded: number, total: number) => void;
+    deps?: {
+        createClient?: (account: ClawHiveResolvedAccount) => Pick<ClawHiveCloudApi, "registerPluginNode" | "createMarketListing" | "uploadReleasePackage" | "createMarketRelease">;
+        packageAgentDirectory?: typeof packageAgentDirectory;
+    };
+}): Promise<PublishFlowResult>;

package/dist/src/market-publish/publishFlow.js

@@ -0,0 +1,107 @@
+import { basename } from "node:path";
+import { ClawHiveCloudApi, } from "../client.js";
+import { packageAgentDirectory } from "./packager.js";
+export function slugifyForListing(value) {
+    const slug = value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return slug || "agent";
+}
+function normalizeVersion(value) {
+    const raw = value?.trim() || "1.0.0";
+    return raw.startsWith("v") ? raw : `v${raw}`;
+}
+export function inferPublishDefaults(input) {
+    const manifest = input.manifest;
+    const name = manifest.displayName ?? manifest.name ?? input.folderName;
+    return {
+        name,
+        slug: slugifyForListing(manifest.name ?? name),
+        summary: manifest.summary ?? manifest.description,
+        authorDisplayName: manifest.author?.name,
+        category: manifest.metadata?.category,
+        license: manifest.metadata?.license,
+        tags: Array.isArray(manifest.metadata?.tags) ? manifest.metadata.tags : [],
+        version: normalizeVersion(manifest.version),
+        sourceRef: input.sourceRef,
+        minOpenClawVersion: manifest.compatibility?.minOpenClawVersion ?? input.account?.minOpenClawVersion ?? undefined,
+        minPluginVersion: manifest.compatibility?.minPluginVersion ?? input.account?.minPluginVersion ?? undefined,
+    };
+}
+export async function runPublishFlow(input) {
+    if (!input.account.pluginToken) {
+        throw new Error("ClawHive is not authorized. Run `openclaw clawhive authorize` first.");
+    }
+    const defaults = inferPublishDefaults({
+        folderName: input.agent.name || basename(input.agent.path),
+        manifest: input.agent.manifest,
+        sourceRef: input.sourceRef,
+        account: input.account,
+    });
+    const publish = { ...defaults, ...input.overrides };
+    const createClient = input.deps?.createClient ??
+        ((account) => new ClawHiveCloudApi({
+            projectUrl: account.projectUrl,
+            anonKey: account.anonKey,
+            pluginToken: account.pluginToken,
+            userId: account.userId,
+            pluginNodeId: account.pluginNodeId,
+            nodeName: account.nodeName,
+            pluginVersion: account.pluginVersion,
+        }));
+    const client = createClient(input.account);
+    const registration = await client.registerPluginNode();
+    const accessToken = registration.user_session.access_token;
+    const listingInput = {
+        accessToken,
+        listingId: input.overrides.listingId,
+        name: publish.name,
+        slug: publish.slug,
+        authorDisplayName: publish.authorDisplayName,
+        summary: publish.summary,
+        category: publish.category,
+        license: publish.license,
+        tags: publish.tags,
+        status: "draft",
+    };
+    const listingResponse = await client.createMarketListing(listingInput);
+    const listing = listingResponse.listing;
+    const listingId = String(listing.id);
+    const packageFn = input.deps?.packageAgentDirectory ?? packageAgentDirectory;
+    const packageResult = await packageFn({ agentDir: input.agent.path });
+    const upload = await client.uploadReleasePackage({
+        listingId,
+        version: publish.version,
+        buffer: packageResult.buffer,
+        fingerprint: packageResult.fingerprint,
+        accessToken,
+        onProgress: input.onProgress,
+    });
+    const releaseInput = {
+        accessToken,
+        listingId,
+        version: publish.version,
+        storagePath: upload.storage_path,
+        fingerprint: upload.fingerprint,
+        sourceType: "manifest",
+        sourceRef: publish.sourceRef,
+        publish: true,
+        minPluginVersion: publish.minPluginVersion,
+        minOpenClawVersion: publish.minOpenClawVersion,
+    };
+    const releaseResponse = await client.createMarketRelease(releaseInput);
+    const release = releaseResponse.release;
+    return {
+        listingId,
+        releaseId: release.id ? String(release.id) : null,
+        version: publish.version,
+        storagePath: upload.storage_path,
+        fingerprint: upload.fingerprint,
+        listing,
+        release,
+    };
+}

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

@@ -0,0 +1,73 @@
+import type { ClawHiveCloudApi } from "../client.js";
+export type UploadResult = {
+    storagePath: string;
+    fingerprint: string;
+    sizeBytes: number;
+};
+export type UploadOptions = {
+    listingId: string;
+    version: string;
+    buffer: Buffer;
+    fingerprint: string;
+    accessToken: string;
+    onProgress?: (bytesUploaded: number, totalBytes: number) => void;
+};
+export declare class UploadFailedError extends Error {
+    readonly attempts: number;
+    constructor(message: string, attempts: number, cause?: unknown);
+}
+/**
+ * Uploads a release package to Supabase Storage with retry logic.
+ *
+ * Per D-08, D-09, D-10, D-11:
+ * - Two-step publish flow: upload first, then create release record
+ * - Storage path: releases/{listing_id}/{version}.tar.gz
+ * - Size limit: 10 MiB (checked by edge function)
+ * - Retry: exponential backoff with jitter, max 3 attempts
+ * - Idempotency: uploading same content to same path is safe
+ *
+ * @param client - ClawHiveCloudApi instance
+ * @param options - Upload options
+ * @returns Upload result with storage path and fingerprint
+ * @throws {UploadFailedError} if all retry attempts fail
+ */
+export declare function uploadReleasePackage(client: ClawHiveCloudApi, options: UploadOptions): Promise<UploadResult>;
+/**
+ * Two-step publish flow helper that packages, uploads, and returns data for release creation.
+ *
+ * This is a convenience wrapper that combines packaging and upload.
+ * The caller must still call market-releases-create with the returned data.
+ *
+ * Example usage:
+ * ```typescript
+ * import { packageAndUpload } from "./market-publish/uploader.js";
+ * import { packageAgentDirectory } from "./market-publish/packager.js";
+ *
+ * // Step 1: Package and upload
+ * const uploadResult = await packageAndUpload(client, {
+ *   agentDir: "/path/to/agent",
+ *   listingId: "listing-uuid",
+ *   version: "v1.0.0",
+ *   accessToken: "user-jwt",
+ * });
+ *
+ * // Step 2: Create release record (caller's responsibility)
+ * await client.createMarketRelease({
+ *   listingId: uploadResult.listingId,
+ *   version: uploadResult.version,
+ *   storagePath: uploadResult.storagePath,
+ *   fingerprint: uploadResult.fingerprint,
+ *   // ... other release metadata
+ * });
+ * ```
+ */
+export declare function packageAndUpload(client: ClawHiveCloudApi, options: {
+    agentDir: string;
+    listingId: string;
+    version: string;
+    accessToken: string;
+    onProgress?: (bytesUploaded: number, totalBytes: number) => void;
+}): Promise<UploadResult & {
+    listingId: string;
+    version: string;
+}>;

package/dist/src/market-publish/uploader.js

@@ -0,0 +1,132 @@
+export class UploadFailedError extends Error {
+    attempts;
+    constructor(message, attempts, cause) {
+        super(message);
+        this.attempts = attempts;
+        this.name = "UploadFailedError";
+        if (cause instanceof Error) {
+            this.cause = cause;
+        }
+    }
+}
+const MAX_RETRY_ATTEMPTS = 3;
+const INITIAL_BACKOFF_MS = 1000;
+const BACKOFF_MULTIPLIER = 2;
+const JITTER_MAX_MS = 500;
+/**
+ * Uploads a release package to Supabase Storage with retry logic.
+ *
+ * Per D-08, D-09, D-10, D-11:
+ * - Two-step publish flow: upload first, then create release record
+ * - Storage path: releases/{listing_id}/{version}.tar.gz
+ * - Size limit: 10 MiB (checked by edge function)
+ * - Retry: exponential backoff with jitter, max 3 attempts
+ * - Idempotency: uploading same content to same path is safe
+ *
+ * @param client - ClawHiveCloudApi instance
+ * @param options - Upload options
+ * @returns Upload result with storage path and fingerprint
+ * @throws {UploadFailedError} if all retry attempts fail
+ */
+export async function uploadReleasePackage(client, options) {
+    const { listingId, version, buffer, fingerprint, accessToken, onProgress } = options;
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
+        try {
+            // Report progress at start of attempt
+            if (onProgress) {
+                onProgress(0, buffer.length);
+            }
+            const result = await client.uploadReleasePackage({
+                listingId,
+                version,
+                buffer,
+                fingerprint,
+                accessToken,
+            });
+            // Report progress at completion
+            if (onProgress) {
+                onProgress(buffer.length, buffer.length);
+            }
+            return {
+                storagePath: result.storage_path,
+                fingerprint: result.fingerprint,
+                sizeBytes: buffer.length,
+            };
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry on client errors (4xx) - these are permanent failures
+            if (error &&
+                typeof error === "object" &&
+                "status" in error &&
+                typeof error.status === "number" &&
+                error.status >= 400 &&
+                error.status < 500) {
+                throw new UploadFailedError(`Upload failed with client error (${error.status}): ${error instanceof Error ? error.message : String(error)}`, attempt, error);
+            }
+            // If this was the last attempt, throw
+            if (attempt === MAX_RETRY_ATTEMPTS) {
+                break;
+            }
+            // Calculate backoff with exponential increase and jitter
+            const backoffMs = INITIAL_BACKOFF_MS * Math.pow(BACKOFF_MULTIPLIER, attempt - 1);
+            const jitterMs = Math.random() * JITTER_MAX_MS;
+            const delayMs = backoffMs + jitterMs;
+            // Wait before retry
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    // All attempts failed
+    throw new UploadFailedError(`Upload failed after ${MAX_RETRY_ATTEMPTS} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`, MAX_RETRY_ATTEMPTS, lastError);
+}
+/**
+ * Two-step publish flow helper that packages, uploads, and returns data for release creation.
+ *
+ * This is a convenience wrapper that combines packaging and upload.
+ * The caller must still call market-releases-create with the returned data.
+ *
+ * Example usage:
+ * ```typescript
+ * import { packageAndUpload } from "./market-publish/uploader.js";
+ * import { packageAgentDirectory } from "./market-publish/packager.js";
+ *
+ * // Step 1: Package and upload
+ * const uploadResult = await packageAndUpload(client, {
+ *   agentDir: "/path/to/agent",
+ *   listingId: "listing-uuid",
+ *   version: "v1.0.0",
+ *   accessToken: "user-jwt",
+ * });
+ *
+ * // Step 2: Create release record (caller's responsibility)
+ * await client.createMarketRelease({
+ *   listingId: uploadResult.listingId,
+ *   version: uploadResult.version,
+ *   storagePath: uploadResult.storagePath,
+ *   fingerprint: uploadResult.fingerprint,
+ *   // ... other release metadata
+ * });
+ * ```
+ */
+export async function packageAndUpload(client, options) {
+    const { packageAgentDirectory } = await import("./packager.js");
+    // Package the agent directory
+    const packageResult = await packageAgentDirectory({
+        agentDir: options.agentDir,
+    });
+    // Upload to Storage
+    const uploadResult = await uploadReleasePackage(client, {
+        listingId: options.listingId,
+        version: options.version,
+        buffer: packageResult.buffer,
+        fingerprint: packageResult.fingerprint,
+        accessToken: options.accessToken,
+        onProgress: options.onProgress,
+    });
+    return {
+        ...uploadResult,
+        listingId: options.listingId,
+        version: options.version,
+    };
+}

package/dist/src/openclawVersion.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolve the current OpenClaw host version from runtime exports or env overrides.
+ */
+export declare function resolveOpenClawVersion(): string | null;

package/dist/src/openclawVersion.js

@@ -0,0 +1,13 @@
+import { OPENCLAW_VERSION } from "openclaw/plugin-sdk/agent-harness";
+/**
+ * Resolve the current OpenClaw host version from runtime exports or env overrides.
+ */
+export function resolveOpenClawVersion() {
+    const fromEnv = process.env.OPENCLAW_VERSION?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return typeof OPENCLAW_VERSION === "string" && OPENCLAW_VERSION.trim()
+        ? OPENCLAW_VERSION
+        : null;
+}

package/dist/src/outbound.d.ts

@@ -0,0 +1,13 @@
+type SendTextContext = {
+    cfg: unknown;
+    to: string;
+    text: string;
+    accountId?: string | null;
+};
+type SendResult = {
+    messageId: string;
+    meta?: Record<string, unknown>;
+};
+export declare function sendAgentText(ctx: SendTextContext): Promise<SendResult>;
+export declare function rejectMedia(): Promise<never>;
+export {};

package/dist/src/outbound.js

@@ -0,0 +1,41 @@
+import { clawhiveRuntimeStore, lookupSession, } from "./runtime.js";
+import { CLAWHIVE_CHANNEL_ID } from "./config.js";
+function stripChannelPrefix(raw) {
+    if (raw.startsWith(`${CLAWHIVE_CHANNEL_ID}:`)) {
+        return raw.slice(CLAWHIVE_CHANNEL_ID.length + 1);
+    }
+    return raw;
+}
+function resolveBinding(runtime, to) {
+    const normalized = stripChannelPrefix(to);
+    return (lookupSession(runtime, to) ??
+        lookupSession(runtime, normalized) ??
+        lookupSession(runtime, `clawhive:default:${normalized}`));
+}
+export async function sendAgentText(ctx) {
+    const runtime = clawhiveRuntimeStore.getRuntime();
+    const binding = resolveBinding(runtime, ctx.to);
+    if (!binding) {
+        throw new Error(`ClawHive outbound: no session binding for target "${ctx.to}"`);
+    }
+    const content = ctx.text?.trim();
+    if (!content) {
+        throw new Error("ClawHive outbound: refusing to send empty text");
+    }
+    const { message } = await runtime.api.writeAgentMessage({
+        pluginNodeId: runtime.pluginNodeId,
+        sessionId: binding.sessionId,
+        agentId: binding.cloudAgentId,
+        content,
+    });
+    return {
+        messageId: message.id,
+        meta: {
+            sequence: message.sequence,
+            createdAt: message.created_at,
+        },
+    };
+}
+export async function rejectMedia() {
+    throw new Error("ClawHive plugin does not yet support outbound media attachments (MVP scope).");
+}

package/dist/src/pairing.d.ts

@@ -0,0 +1,32 @@
+import type { ClawHiveCloudApi, PluginRegisterResult } from "./client.js";
+export type PairingPrintResult = {
+    pairToken: string;
+    expiresAt: string;
+    payloadUrl: string;
+    qrText: string;
+};
+export type PairingPrintOptions = {
+    api: ClawHiveCloudApi;
+    pluginNodeId: string;
+    ttlSeconds?: number;
+    ascii?: (text: string) => void;
+    /** Optional banner printed above the QR. */
+    banner?: string;
+};
+export declare function generatePairingPayload(api: ClawHiveCloudApi, pluginNodeId: string, ttlSeconds?: number): Promise<{
+    pairToken: string;
+    expiresAt: string;
+    payloadUrl: string;
+}>;
+export declare function renderQrText(payloadUrl: string): Promise<string>;
+export declare function printPairingQr(options: PairingPrintOptions): Promise<PairingPrintResult>;
+/**
+ * Return the number of active paired devices for the current user.
+ * Uses the user-scoped session minted by plugin-register so the query
+ * passes RLS without bringing service-role credentials into the plugin.
+ */
+export declare function getPairedDeviceCount(params: {
+    registration: PluginRegisterResult;
+    projectUrl: string;
+    anonKey: string;
+}): Promise<number>;