Skip to content

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.yml
index 40a344fd..63bf3151 100644
--- a/.github/workflows/ci-plugin.yml
+++ b/.github/workflows/ci-plugin.yml
@@ -1,6 +1,12 @@
name: CI / Plugin
on:
+ 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.yml
with:
- ref: ${{ github.sha }}
+ ref: ${{ inputs.ref || github.sha }}
diff --git a/.github/workflows/reusable-plugin.yml b/.github/workflows/reusable-plugin.yml
index 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 schemas
working-directory: plugin
run: |
@@ -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 contents
working-directory: plugin
run: |
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 Plugin
runs-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 tests
working-directory: plugin
- run: npx tsx --test *.test.ts
+ run: npm test
diff --git a/.github/workflows/reusable-publish-plugin.yml b/.github/workflows/reusable-publish-plugin.yml
index 38da9b55..02cbccd6 100644
--- a/.github/workflows/reusable-publish-plugin.yml
+++ b/.github/workflows/reusable-publish-plugin.yml
@@ -6,14 +6,24 @@ on:
version:
required: true
type: string
+ ref:
+ required: false
+ type: string
+ default: ''
secrets:
NPM_TOKEN:
required: true
+ CLAWHUB_TOKEN:
+ required: true
workflow_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 plugin
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
+ with:
+ ref: ${{ inputs.ref || github.ref }}
- uses: actions/setup-node@v6
with:
@@ -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: Summary
env:
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.yml
index bf26c87c..f4c6f545 100644
--- a/.github/workflows/reusable-publish-skill.yml
+++ b/.github/workflows/reusable-publish-skill.yml
@@ -6,6 +6,10 @@ on:
version:
required: true
type: 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-latest
steps:
- uses: actions/checkout@v6
+ with:
+ ref: ${{ inputs.ref || github.ref }}
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/reusable-release-publish.yml b/.github/workflows/reusable-release-publish.yml
index 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.yml
with:
version: ${{ inputs.tag }}
+ ref: ${{ inputs.ref }}
secrets:
CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
@@ -175,5 +176,7 @@ jobs:
uses: ./.github/workflows/reusable-publish-plugin.yml
with:
version: ${{ inputs.tag }}
+ ref: ${{ inputs.ref }}
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+ CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
diff --git a/RELEASE.md b/RELEASE.md
index 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 a
2. **Creates GitHub release** — with checksums.txt for integrity verification
3. **Publishes to npm** — TypeScript SDK with auto-download postinstall script
4. **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 packages
Depends 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.
## Troubleshooting
diff --git a/plugin/index.ts b/plugin/index.ts
index 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 tool
if (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.ts
new file mode 100644
index 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.json
index 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.json
new file mode 100644
index 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.ts
index 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<