High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add clawhub plugin publish and API contract checks
Luigi Agostibac6b1908ccd
diff --git a/.github/workflows/ci-plugin.yml b/.github/workflows/ci-plugin.ymlindex 40a344fd..63bf3151 100644--- a/.github/workflows/ci-plugin.yml+++ b/.github/workflows/ci-plugin.yml@@ -1,6 +1,12 @@name: CI / Pluginon:+ workflow_dispatch:+ inputs:+ ref:+ description: 'Git ref to check. Defaults to the workflow ref.'+ required: false+ default: ''push:branches: [main]paths:@@ -18,4 +24,4 @@ jobs:plugin:uses: ./.github/workflows/reusable-plugin.ymlwith:- ref: ${{ github.sha }}+ ref: ${{ inputs.ref || github.sha }}diff --git a/.github/workflows/reusable-plugin.yml b/.github/workflows/reusable-plugin.ymlindex 6f7038de..fb1370f9 100644--- a/.github/workflows/reusable-plugin.yml+++ b/.github/workflows/reusable-plugin.yml@@ -24,6 +24,10 @@ jobs:with:node-version: '22'+ - name: Install plugin dependencies+ working-directory: plugin+ run: npm install --ignore-scripts --no-package-lock+- name: Verify JSON schemasworking-directory: pluginrun: |@@ -31,12 +35,19 @@ jobs:node -e "JSON.parse(require('fs').readFileSync('openclaw.plugin.json', 'utf8'))"echo "✅ All JSON files are valid"+ - name: Verify OpenClaw plugin API types+ working-directory: plugin+ run: npm run typecheck+- name: Verify package contentsworking-directory: pluginrun: |echo "📦 Package will contain:"npm pack --dry-run 2>&1 | grep -E "^npm notice [0-9]" | awk '{print " " $4 " (" $3 ")"}'+ - name: Verify ClawHub package metadata+ run: npx --yes clawhub@latest package publish ./plugin --family code-plugin --dry-run --json+test:name: Test Pluginruns-on: ubuntu-latest@@ -49,6 +60,10 @@ jobs:with:node-version: '22'+ - name: Install plugin dependencies+ working-directory: plugin+ run: npm install --ignore-scripts --no-package-lock+- name: Run testsworking-directory: plugin- run: npx tsx --test *.test.ts+ run: npm testdiff --git a/.github/workflows/reusable-publish-plugin.yml b/.github/workflows/reusable-publish-plugin.ymlindex 38da9b55..02cbccd6 100644--- a/.github/workflows/reusable-publish-plugin.yml+++ b/.github/workflows/reusable-publish-plugin.yml@@ -6,14 +6,24 @@ on:version:required: truetype: string+ ref:+ required: false+ type: string+ default: ''secrets:NPM_TOKEN:required: true+ CLAWHUB_TOKEN:+ required: trueworkflow_dispatch:inputs:version:description: 'Plugin version (e.g. 0.3.0, without v prefix)'required: true+ ref:+ description: 'Git ref to publish from. Defaults to the workflow ref.'+ required: false+ default: ''permissions:@@ -21,10 +31,12 @@ permissions:jobs:publish:- name: Publish to npm+ name: Publish pluginruns-on: ubuntu-lateststeps:- uses: actions/checkout@v6+ with:+ ref: ${{ inputs.ref || github.ref }}- uses: actions/setup-node@v6with:@@ -72,6 +84,34 @@ jobs:env:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ - name: Install ClawHub CLI+ run: npm i -g clawhub++ - name: Authenticate with ClawHub+ run: clawhub login --token "$CLAWHUB_TOKEN" --no-browser+ env:+ CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}++ - name: Publish to ClawHub+ env:+ VERSION: ${{ steps.version.outputs.value }}+ CHECKOUT_REF: ${{ inputs.ref || github.ref }}+ run: |+ SOURCE_REF="$CHECKOUT_REF"+ SOURCE_REF="${SOURCE_REF#refs/tags/}"+ SOURCE_REF="${SOURCE_REF#refs/heads/}"+ SOURCE_REF="${SOURCE_REF#refs/remotes/}"++ clawhub package publish ./plugin \+ --family code-plugin \+ --version "$VERSION" \+ --changelog "Release v$VERSION" \+ --tags latest \+ --source-repo pinchtab/pinchtab \+ --source-commit "$(git rev-parse HEAD)" \+ --source-ref "$SOURCE_REF" \+ --source-path plugin+- name: Summaryenv:VERSION: ${{ steps.version.outputs.value }}@@ -79,4 +119,5 @@ jobs:echo "## Plugin Published" >> "$GITHUB_STEP_SUMMARY"echo "- Package: @pinchtab/pinchtab" >> "$GITHUB_STEP_SUMMARY"echo "- Version: $VERSION" >> "$GITHUB_STEP_SUMMARY"- echo "- Install: \`openclaw plugins install @pinchtab/pinchtab\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- npm: \`openclaw plugins install @pinchtab/pinchtab\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- ClawHub: \`openclaw plugins install clawhub:@pinchtab/pinchtab\`" >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/reusable-publish-skill.yml b/.github/workflows/reusable-publish-skill.ymlindex bf26c87c..f4c6f545 100644--- a/.github/workflows/reusable-publish-skill.yml+++ b/.github/workflows/reusable-publish-skill.yml@@ -6,6 +6,10 @@ on:version:required: truetype: string+ ref:+ required: false+ type: string+ default: ''secrets:CLAWHUB_TOKEN:required: true@@ -14,6 +18,10 @@ on:version:description: 'Skill version (e.g. 0.2.0, without v prefix)'required: true+ ref:+ description: 'Git ref to publish from. Defaults to the workflow ref.'+ required: false+ default: ''permissions:@@ -25,6 +33,8 @@ jobs:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v6+ with:+ ref: ${{ inputs.ref || github.ref }}- uses: actions/setup-node@v6with:diff --git a/.github/workflows/reusable-release-publish.yml b/.github/workflows/reusable-release-publish.ymlindex 89a89d85..8aa834d2 100644--- a/.github/workflows/reusable-release-publish.yml+++ b/.github/workflows/reusable-release-publish.yml@@ -164,6 +164,7 @@ jobs:uses: ./.github/workflows/reusable-publish-skill.ymlwith:version: ${{ inputs.tag }}+ ref: ${{ inputs.ref }}secrets:CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}@@ -175,5 +176,7 @@ jobs:uses: ./.github/workflows/reusable-publish-plugin.ymlwith:version: ${{ inputs.tag }}+ ref: ${{ inputs.ref }}secrets:NPM_TOKEN: ${{ secrets.NPM_TOKEN }}+ CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}diff --git a/RELEASE.md b/RELEASE.mdindex 04b4e6b6..c1524421 100644--- a/RELEASE.md+++ b/RELEASE.md@@ -8,7 +8,7 @@ Pinchtab uses an automated CI/CD pipeline triggered by Git tags. When you push a2. **Creates GitHub release** — with checksums.txt for integrity verification3. **Publishes to npm** — TypeScript SDK with auto-download postinstall script4. **Builds Docker images** — linux/amd64, linux/arm64-5. **Publishes the ClawHub skill** — after npm succeeds+5. **Publishes ClawHub packages** — the skill and OpenClaw plugin publish in parallel after npm succeeds## Prerequisites@@ -22,6 +22,7 @@ Go to **Settings → Secrets and variables → Actions** and add:- **DOCKERHUB_USER** — Docker Hub username (if using Docker Hub)- **DOCKERHUB_TOKEN** — Docker Hub personal access token+- **CLAWHUB_TOKEN** — ClawHub authentication token for publishing the skill and OpenClaw plugin### Local setup@@ -82,6 +83,7 @@ grep -A 2 "^release:" .goreleaser.yml- Go checks- dashboard checks- npm package verification+ - OpenClaw plugin verification- docs verification- full release E2E- Docker bootstrap smoke test@@ -94,6 +96,7 @@ grep -A 2 "^release:" .goreleaser.yml- npm publish- Docker image publish- ClawHub skill publish+ - ClawHub plugin publish### Required GitHub setup@@ -156,13 +159,14 @@ Depends on: `release` and `npm`GitHub Actions builds the release image directly from the tagged source with `docker buildx`.The workflow pushes the same multi-arch build to both GHCR and Docker Hub, but only after npm has already published successfully.-### 4. ClawHub skill+### 4. ClawHub packagesDepends on: `release` and `npm`-The main `Release` workflow publishes the Pinchtab skill to ClawHub automatically after npm succeeds.-It does not consume npm artifacts or GitHub release binaries directly; the ordering is a policy choice so npm stays the first irreversible publish step.-The standalone `Publish Skill` workflow remains available for retries or one-off recovery publishes.+The main `Release` workflow publishes the Pinchtab skill and OpenClaw plugin to ClawHub automatically after npm succeeds.+They run as separate jobs at the same dependency level, so the plugin publish happens in parallel with the skill publish.+Neither ClawHub publish consumes npm artifacts or GitHub release binaries directly; the ordering is a policy choice so npm stays the first irreversible publish step.+The standalone publish workflows remain available for retries or one-off recovery publishes.## Troubleshootingdiff --git a/plugin/index.ts b/plugin/index.tsindex d5b243a3..fd2e2295 100644--- a/plugin/index.ts+++ b/plugin/index.ts@@ -6,42 +6,40 @@* - `browser`: OpenClaw-compatible simplified interface*/-import type { PluginApi, PluginConfig } from "./types.js";+import type { PluginApi, PluginConfig, PluginTool } from "./types.js";import { pinchtabToolSchema, pinchtabToolDescription, executePinchtabAction } from "./tools/pinchtab.js";import { browserToolSchema, browserToolDescription, executeBrowserAction } from "./tools/browser.js";function getConfig(api: PluginApi): PluginConfig {- return api.config?.plugins?.entries?.pinchtab?.config ?? {};+ return (api.pluginConfig ?? api.config?.plugins?.entries?.pinchtab?.config ?? {}) as PluginConfig;}export default function register(api: PluginApi) {const cfg = getConfig(api);// Register the full-featured pinchtab tool- api.registerTool(- {- name: "pinchtab",- description: pinchtabToolDescription,- parameters: pinchtabToolSchema,- async execute(_id: string, params: any) {- return executePinchtabAction(getConfig(api), params);- },+ const pinchtabTool = {+ name: "pinchtab",+ label: "PinchTab",+ description: pinchtabToolDescription,+ parameters: pinchtabToolSchema,+ async execute(_id: string, params: any) {+ return executePinchtabAction(getConfig(api), params);},- { optional: true },- );+ } satisfies PluginTool;+ api.registerTool(pinchtabTool, { optional: true });// Register OpenClaw-compatible browser toolif (cfg.registerBrowserTool !== false) {- api.registerTool(- {- name: "browser",- description: browserToolDescription,- parameters: browserToolSchema,- async execute(_id: string, params: any) {- return executeBrowserAction(getConfig(api), params);- },+ const browserTool = {+ name: "browser",+ label: "Browser",+ description: browserToolDescription,+ parameters: browserToolSchema,+ async execute(_id: string, params: any) {+ return executeBrowserAction(getConfig(api), params);},- { optional: true },- );+ } satisfies PluginTool;+ api.registerTool(browserTool, { optional: true });}}diff --git a/plugin/openclaw-api.test.ts b/plugin/openclaw-api.test.tsnew file mode 100644index 00000000..2b47877c--- /dev/null+++ b/plugin/openclaw-api.test.ts@@ -0,0 +1,141 @@+import { describe, it } from "node:test";+import assert from "node:assert";+import type { AnyAgentTool, OpenClawPluginApi, PluginLogger, PluginRuntime } from "openclaw/plugin-sdk";+import register from "./index.ts";++type RegisteredToolOptions = Parameters<OpenClawPluginApi["registerTool"]>[1];+type TestPluginApiInput = Partial<OpenClawPluginApi>;++function createTestPluginApi(api: TestPluginApiInput): OpenClawPluginApi {+ const logger: PluginLogger = {+ info() {},+ warn() {},+ error() {},+ debug() {},+ };++ return {+ id: "pinchtab",+ name: "PinchTab",+ source: "test",+ registrationMode: "full",+ config: {},+ runtime: {} as PluginRuntime,+ logger,+ registerTool() {},+ registerHook() {},+ registerHttpRoute() {},+ registerChannel() {},+ registerGatewayMethod() {},+ registerCli() {},+ registerReload() {},+ registerNodeHostCommand() {},+ registerSecurityAuditCollector() {},+ registerService() {},+ registerGatewayDiscoveryService() {},+ registerCliBackend() {},+ registerTextTransforms() {},+ registerConfigMigration() {},+ registerMigrationProvider() {},+ registerAutoEnableProbe() {},+ registerProvider() {},+ registerSpeechProvider() {},+ registerRealtimeTranscriptionProvider() {},+ registerRealtimeVoiceProvider() {},+ registerMediaUnderstandingProvider() {},+ registerImageGenerationProvider() {},+ registerMusicGenerationProvider() {},+ registerVideoGenerationProvider() {},+ registerWebFetchProvider() {},+ registerWebSearchProvider() {},+ registerInteractiveHandler() {},+ onConversationBindingResolved() {},+ registerCommand() {},+ registerContextEngine() {},+ registerCompactionProvider() {},+ registerAgentHarness() {},+ registerCodexAppServerExtensionFactory() {},+ registerAgentToolResultMiddleware() {},+ registerDetachedTaskRuntime() {},+ registerSessionExtension() {},+ enqueueNextTurnInjection: async (injection) => ({+ enqueued: false,+ id: "",+ sessionKey: injection.sessionKey,+ }),+ registerTrustedToolPolicy() {},+ registerToolMetadata() {},+ registerControlUiDescriptor() {},+ registerRuntimeLifecycle() {},+ registerAgentEventSubscription() {},+ setRunContext: () => false,+ getRunContext: () => undefined,+ clearRunContext() {},+ registerSessionSchedulerJob: () => undefined,+ registerMemoryCapability() {},+ registerMemoryPromptSection() {},+ registerMemoryPromptSupplement() {},+ registerMemoryCorpusSupplement() {},+ registerMemoryFlushPlan() {},+ registerMemoryRuntime() {},+ registerMemoryEmbeddingProvider() {},+ resolvePath(input) {+ return input;+ },+ on() {},+ ...api,+ };+}++describe("OpenClaw plugin API contract", () => {+ it("registers tools through the official OpenClaw plugin API", () => {+ const registered: Array<{ tool: AnyAgentTool; opts?: RegisteredToolOptions }> = [];+ const api = createTestPluginApi({+ id: "pinchtab",+ name: "Pinchtab",+ pluginConfig: { registerBrowserTool: true },+ config: {+ plugins: {+ entries: {+ pinchtab: { config: { registerBrowserTool: true } },+ },+ },+ },+ registerTool(tool, opts) {+ assert.strictEqual(typeof tool, "object");+ registered.push({ tool: tool as AnyAgentTool, opts });+ },+ });++ register(api);++ assert.deepStrictEqual(+ registered.map(({ tool }) => tool.name).sort(),+ ["browser", "pinchtab"],+ );+ for (const { tool, opts } of registered) {+ assert.strictEqual(typeof tool.label, "string");+ assert.strictEqual(typeof tool.description, "string");+ assert.strictEqual(typeof tool.execute, "function");+ assert.strictEqual((tool.parameters as { type?: string }).type, "object");+ assert.strictEqual(opts?.optional, true);+ }+ });++ it("honors pluginConfig when suppressing the compatibility browser tool", () => {+ const names: string[] = [];+ const api = createTestPluginApi({+ id: "pinchtab",+ name: "Pinchtab",+ pluginConfig: { registerBrowserTool: false },+ registerTool(tool) {+ assert.strictEqual(typeof tool, "object");+ names.push((tool as AnyAgentTool).name);+ },+ });++ register(api);++ assert.deepStrictEqual(names, ["pinchtab"]);+ });+});diff --git a/plugin/package.json b/plugin/package.jsonindex 985a8c00..55a2d095 100644--- a/plugin/package.json+++ b/plugin/package.json@@ -1,13 +1,21 @@{"name": "@pinchtab/pinchtab","version": "0.3.0",- "description": "OpenClaw plugin for Pinchtab browser control",+ "description": "OpenClaw plugin for PinchTab browser control","type": "module","scripts": {- "test": "npx tsx --test *.test.ts"+ "test": "tsx --test *.test.ts",+ "typecheck": "tsc -p tsconfig.json --noEmit",+ "check": "npm run typecheck && npm test"},"openclaw": {- "extensions": ["./index.ts"]+ "extensions": ["./index.ts"],+ "compat": {+ "pluginApi": ">=2026.3.24-beta.2"+ },+ "build": {+ "openclawVersion": "2026.4.27"+ }},"files": ["index.ts",@@ -18,5 +26,11 @@"tools/","openclaw.plugin.json"],- "license": "MIT"+ "license": "MIT",+ "devDependencies": {+ "@types/node": "^22.15.3",+ "openclaw": "2026.4.27",+ "tsx": "^4.20.6",+ "typescript": "^5.9.3"+ }}diff --git a/plugin/tsconfig.json b/plugin/tsconfig.jsonnew file mode 100644index 00000000..cf67765c--- /dev/null+++ b/plugin/tsconfig.json@@ -0,0 +1,13 @@+{+ "compilerOptions": {+ "allowImportingTsExtensions": true,+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "noEmit": true,+ "skipLibCheck": true,+ "strict": true,+ "target": "ES2022",+ "types": ["node"]+ },+ "include": ["*.ts", "tools/*.ts"]+}diff --git a/plugin/types.ts b/plugin/types.tsindex 0f52703c..4bdb7dba 100644--- a/plugin/types.ts+++ b/plugin/types.ts@@ -1,3 +1,5 @@+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";+export interface PluginConfig {baseUrl?: string;token?: string;@@ -22,10 +24,8 @@ export interface PluginConfig {profiles?: Record<string, { instanceId?: string; attach?: boolean }>;}-export interface PluginApi {- config: { plugins?: { entries?: Record<string, { config?: PluginConfig }> } };- registerTool: (tool: any, opts?: { optional?: boolean }) => void;-}+export type PluginApi = OpenClawPluginApi;+export type PluginTool = AnyAgentTool;export interface ToolResult {content: Array<