feat: add OpenClaw plugin for seamless maple-proxy integration

[AnthonyRonning]

Summary

Adds an OpenClaw plugin (@opensecret/maple-proxy-openclaw-plugin) that automatically downloads, manages, and runs the maple-proxy binary as a background service within OpenClaw. Users install the plugin, provide an API key, and get immediate access to Maple's TEE-backed AI models -- no manual setup needed.

Closes #12

What's included

openclaw-plugin/ directory (new)

• index.ts -- Plugin entry point; registers a background service that starts/stops maple-proxy
• lib/platform.ts -- OS/arch detection, maps to the correct GitHub Release artifact name
• lib/downloader.ts -- Downloads the binary from GitHub Releases, verifies SHA256 checksums, extracts and caches in ~/.openclaw/tools/maple-proxy/
• lib/process.ts -- Spawns maple-proxy as a child process, finds free ports, waits for health check
• openclaw.plugin.json -- Plugin manifest with config schema (apiKey required, port/backendUrl/debug optional) and UI hints
• package.json -- npm package @opensecret/maple-proxy-openclaw-plugin
• skills/maple-proxy-skill/SKILL.md -- AgentSkills-compatible skill, gated on plugin being enabled

Dev tooling updates

• flake.nix -- Added nodejs_22 to commonInputs so TypeScript plugin dev works in the Nix devShell
• justfile -- Added plugin-install, plugin-build, plugin-lint, plugin-test, check-all, plugin-link, plugin-pack, plugin-publish commands

Naming convention

maple-proxy is reserved for the Rust binary. All plugin/skill names use a maple-proxy- prefix:

• Plugin id: maple-proxy-openclaw-plugin
• npm package: @opensecret/maple-proxy-openclaw-plugin
• Skill name: maple-proxy-skill

User experience

openclaw plugins install @opensecret/maple-proxy-openclaw-plugin

Then in openclaw.json:

{
  "plugins": {
    "entries": {
      "maple-proxy-openclaw-plugin": {
        "enabled": true,
        "config": { "apiKey": "sk-..." }
      }
    }
  }
}

Restart the gateway -- the plugin downloads the binary, starts it, and the skill becomes available to the agent.

No changes to Rust source

The src/ directory is completely untouched. The existing release CI (release.yml) already builds binaries for all 4 platforms that the plugin downloads from.

---

Summary by CodeRabbit

Release Notes

• New Features

  • Maple Proxy plugin now available for OpenClaw, enabling integration with Maple TEE-backed AI models.
  • New maple_proxy_status tool to monitor proxy health and system metrics.
  • Plugin auto-manages binary downloads, versioning, and platform compatibility.

• Documentation

  • Added comprehensive plugin setup, configuration, and troubleshooting guides.
  • Included skill documentation for Maple model integration with memory search capabilities.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR introduces an OpenClaw plugin for maple-proxy that automates binary download, caching, and lifecycle management. It includes platform-specific artifact resolution, background service orchestration, health checks, a proxy status tool, build configuration updates, and comprehensive documentation.

Changes

Cohort / File(s)	Summary
Build Configuration flake.nix, justfile	Added Node.js 22 to devShell inputs; introduced 8 new plugin-focused targets (install, build, lint, test, link, pack, publish) and a composite check-all target for CI integration.
Plugin Manifest & Package openclaw-plugin/openclaw.plugin.json, openclaw-plugin/package.json, openclaw-plugin/tsconfig.json	Defined plugin metadata (id, name, config schema with apiKey, port, debug); declared npm package as @opensecret/maple-proxy-openclaw-plugin with TypeScript build and test scripts; configured TypeScript compiler for strict mode and source maps.
Plugin Entry Point openclaw-plugin/index.ts	Implemented plugin registration with background service (start/stop lifecycle, binary validation, proxy spawning), status tool for agent queries, and public API exports (id, name, register function, config interfaces).
Binary Download & Platform Logic openclaw-plugin/lib/downloader.ts, openclaw-plugin/lib/platform.ts	Created download orchestration with caching, SHA-256 verification, extraction (tar.gz/zip), and cleanup; platform detection for linux/darwin/win32 with artifact name and URL construction.
Process Management openclaw-plugin/lib/process.ts	Implemented child process spawning, environment variable mapping, startup health checks, automatic restart with exponential backoff (up to 3 retries), and graceful termination.
Testing & Documentation openclaw-plugin/lib/downloader.test.ts, openclaw-plugin/README.md, openclaw-plugin/skills/maple-proxy-skill/SKILL.md	Added comprehensive version comparison tests; provided quick-start and troubleshooting guides; documented skill configuration for Maple model access via local proxy endpoint.
Project Scaffolding openclaw-plugin/.gitignore	Added ignore patterns for node_modules, dist, and tgz archives.

Sequence Diagram(s)

sequenceDiagram
    participant User as User/Gateway
    participant Plugin as Plugin Service
    participant DL as Downloader
    participant Platform as Platform Detect
    participant GH as GitHub Releases
    participant Process as Process Manager
    participant Proxy as maple-proxy<br/>Process
    participant Health as Health Check

    User->>Plugin: start()
    activate Plugin
    Plugin->>Plugin: validate apiKey
    Plugin->>DL: ensureBinary(logger)
    activate DL
    DL->>Platform: getArtifact()
    activate Platform
    Platform-->>DL: {name, archiveType}
    deactivate Platform
    DL->>Platform: resolveVersion(ttl cache)
    DL->>GH: fetch latest tag
    activate GH
    GH-->>DL: version string
    deactivate GH
    DL->>GH: download artifact
    DL->>GH: download & verify checksum
    DL->>DL: extract (tar.gz/zip)
    DL->>DL: set permissions
    DL-->>Plugin: {binaryPath, version}
    deactivate DL
    Plugin->>Process: startProxy(config, version)
    activate Process
    Process->>Process: verify port available
    Process->>Proxy: spawn with env vars
    activate Proxy
    Proxy-->>Process: process started
    Process->>Health: GET /health (race)
    activate Health
    Health-->>Process: {status, port, ...}
    deactivate Health
    Process-->>Plugin: RunningProxy object
    deactivate Process
    Plugin-->>User: service running
    deactivate Plugin

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~55 minutes

Possibly related PRs

• feat: add OpenClaw plugin for seamless maple-proxy integration #13: Introduces identical build system and plugin file changes to enable maple-proxy OpenClaw integration.

Poem

🐰 A proxy springs to life with care,
Binaries dance through platform air,
No manual toil, no setup pain—
The plugin reigns, let Maple reign! 🍁

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/openclaw-plugin

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

openclaw-plugin/lib/downloader.ts (1)

136-138: Consider cleaning non‑v version directories too.

Line 136-138 only tracks directories starting with "v". If a user pins "0.1.0" (no v), older non‑v folders won’t be cleaned.

♻️ Suggested tweak

-  const versionDirs = entries
-    .filter((e) => e.startsWith("v"))
+  const versionDirs = entries
+    .filter((e) => /^v?\d+\.\d+\.\d+/.test(e))
     .sort(compareVersionsDesc);

[coderabbitai]

🧹 Nitpick comments (3)

openclaw-plugin/lib/downloader.ts (1)

30-37: Consider adding a timeout to prevent indefinite hangs.

The fetch call has no timeout. If GitHub is unreachable or slow, this could block indefinitely. Consider using AbortController with a reasonable timeout.

♻️ Optional: Add fetch timeout

 async function downloadFile(url: string, dest: string): Promise<void> {
-  const res = await fetch(url, { redirect: "follow" });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 60000);
+  try {
+    const res = await fetch(url, { redirect: "follow", signal: controller.signal });
+    if (!res.ok) {
+      throw new Error(`Download failed: ${res.status} ${res.statusText} (${url})`);
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    await fsp.writeFile(dest, buffer);
+  } finally {
+    clearTimeout(timeout);
+  }
-  if (!res.ok) {
-    throw new Error(`Download failed: ${res.status} ${res.statusText} (${url})`);
-  }
-  const buffer = Buffer.from(await res.arrayBuffer());
-  await fsp.writeFile(dest, buffer);
 }

openclaw-plugin/lib/process.ts (2)

130-143: Unhandled promise in setTimeout async callback.

If waitForHealth throws during restart, the error is logged but the resulting rejected promise from the async callback is silently ignored. While the error handling inside is fine, consider explicitly handling the returned promise to avoid potential unhandled rejection warnings in future Node.js versions.

♻️ Optional: Explicitly void the async callback

-          setTimeout(async () => {
+          setTimeout(() => {
+            void (async () => {
               if (stopped) return;
               try {
                 child = spawnProxy(config, port, logger);
                 setupCrashRecovery(child);
                 await waitForHealth(port);
                 logger.info(`maple-proxy restarted on http://127.0.0.1:${port}`);
                 restartAttempts = 0;
               } catch (err) {
                 logger.error(
                   `Failed to restart maple-proxy: ${err instanceof Error ? err.message : err}`
                 );
               }
-          }, delay);
+            })();
+          }, delay);

---

194-203: Signal ordering: SIGINT→SIGTERM is unconventional for daemon shutdown.

The kill() method sends SIGINT first, then escalates to SIGTERM after 3 seconds. Typically, SIGTERM is the standard "please terminate gracefully" signal, while SIGINT is for interactive interrupts (Ctrl+C). If the proxy doesn't respond to either, consider a final SIGKILL escalation.

This likely works fine in practice, but if the maple-proxy binary follows standard signal conventions, swapping the order might be more idiomatic.

♻️ Optional: Consider SIGTERM→SIGKILL ordering

     kill: () => {
       stopped = true;
       if (exited) return;
-      child.kill("SIGINT");
+      child.kill("SIGTERM");
       setTimeout(() => {
         if (!exited) {
-          child.kill("SIGTERM");
+          child.kill("SIGKILL");
         }
       }, 3000);
     },