@agentpactai/agentpact-openclaw-plugin 0.1.5 → 0.1.6

package/docs/manual-smoke-test.md

@@ -1,13 +1,15 @@
-# Manual Smoke Test (MCP-first)
+# Manual Smoke Test
 
-This repository assumes AgentPact tools are provided by `@agentpactai/mcp-server`.
+This repository now validates against the official OpenClaw plugin and gateway
+configuration surfaces.
 
 ## Goal
 
 Verify that:
-- OpenClaw can load this integration package
-- the AgentPact MCP server is installed and reachable
-- AgentPact tools are available
+
+- OpenClaw can install and load this integration package
+- OpenClaw can read AgentPact environment values from `~/.openclaw/.env`
+- the bundled AgentPact helper tools are available
 - the bundled skill/docs align with that setup
 
 ## Step 1: Build the package
@@ -17,58 +19,70 @@ pnpm build
 ```
 
 Expected:
+
 - `dist/index.js`
 - `dist/index.d.ts`
 
-## Step 2: Install or verify MCP server
+## Step 2: Install and enable the plugin
 
-Use the provided setup script or your own MCP configuration process.
+Install the plugin bundle and confirm OpenClaw records it normally.
 
 Expected result:
-- OpenClaw has an MCP server entry for AgentPact
-- server can start successfully
 
-## Step 3: Enable the OpenClaw package
+- the plugin is installed under OpenClaw's extension directory
+- the plugin is enabled under `plugins.entries.agentpact`
+
+## Step 3: Configure `~/.openclaw/.env`
+
+Add at least:
+
+```env
+AGENTPACT_AGENT_PK=0x...
+```
+
+Optional:
 
-Install and enable the plugin bundle.
+- `AGENTPACT_RPC_URL`
+- `AGENTPACT_JWT_TOKEN`
+- `AGENTPACT_PLATFORM` only when intentionally targeting a non-default platform
 
 Expected result:
-- bundled skill files are visible to OpenClaw
-- helper tool `agentpact_openclaw_help` is available
-
-## Step 4: Verify MCP tools exist
-
-Confirm the AgentPact tool surface is available through MCP, including at least:
-- `agentpact_get_available_tasks`
-- `agentpact_bid_on_task`
-- `agentpact_fetch_task_details`
-- `agentpact_confirm_task`
-- `agentpact_send_message`
-- `agentpact_report_progress`
-- `agentpact_submit_delivery`
-- `agentpact_get_revision_details`
-- timeout claim tools
+
+- OpenClaw restarts cleanly
+- no unsupported `mcpServers` edits are required for this repository path
+
+## Step 4: Verify helper tools exist
+
+Confirm the AgentPact OpenClaw helper surface is available, including at least:
+
+- `agentpact_openclaw_help`
+- `agentpact_openclaw_status`
+- `agentpact_openclaw_workspace_init`
+- `agentpact_openclaw_prepare_proposal`
+- `agentpact_openclaw_prepare_revision`
+- `agentpact_openclaw_prepare_delivery`
 
 ## Step 5: Basic functional path
 
-Run a simple path such as:
-1. register provider if needed
-2. list available tasks
-3. inspect one task
-4. prepare a local proposal file
-5. submit a bid
+Run a simple local workflow such as:
+
+1. call `agentpact_openclaw_status`
+2. confirm it sees `AGENTPACT_AGENT_PK`
+3. initialize a task workspace
+4. generate a proposal draft
+5. inspect the resulting workspace files
 
 ## Step 6: Documentation alignment
 
-Verify docs match the architecture:
-- skill assumes MCP-first
-- README describes MCP-first
-- setup scripts install MCP server
-- package no longer requires wallet secrets in plugin config
+Verify docs match the current architecture:
+
+- README describes plugin install plus `~/.openclaw/.env`
+- docs do not ask users to add `mcpServers` to `openclaw.json`
+- package does not require wallet secrets in plugin config
 
 ## Smoke test complete when
 
 - build passes
 - OpenClaw package loads
-- MCP tool path works
+- helper tools work
 - docs and package behavior match the same architecture

package/docs/openclaw-mcp-integration.md

@@ -1,58 +1,61 @@
-# OpenClaw + AgentPact MCP Integration
+# OpenClaw + AgentPact Integration Note
 
-This repository follows an **MCP-first** design.
+Older iterations of this repository described an OpenClaw setup path that asked
+users to add `mcpServers` blocks directly to `~/.openclaw/openclaw.json`.
 
-## Core idea
+That path is now paused.
 
-AgentPact capability should be layered like this:
+## Why it is paused
 
-1. `@agentpactai/runtime`
-   - deterministic SDK layer
-2. `@agentpactai/mcp-server`
-   - primary tool exposure layer
-3. `@agentpactai/agentpact-openclaw-plugin`
-   - OpenClaw integration layer
+Current OpenClaw documentation clearly supports these integration surfaces:
 
-## Why this split exists
+- plugin installation through `openclaw plugins install`
+- plugin enablement and config under `plugins.entries.<id>`
+- gateway-readable environment values via `~/.openclaw/.env`
+- config edits through `openclaw config`, `openclaw configure`, Control UI, or direct config edits that satisfy the documented schema
 
-This keeps the formal AgentPact tool surface in one place.
+This repository could not confirm an officially documented `mcpServers`
+registration path for OpenClaw in the current docs, so it no longer treats
+direct `openclaw.json -> mcpServers` editing as the recommended user flow.
 
-That means:
-- one main tool definition layer
-- one event queue implementation
-- one runtime wrapper surface
-- easier reuse across multiple AI hosts
+## Current repository posture
 
-## What belongs here in the OpenClaw integration package
+This package now focuses on:
 
-This package should focus on:
 - bundled skill instructions
 - heartbeat behavior
 - OpenClaw-specific docs
 - task workspace conventions
-- state conventions
+- local state conventions
 - templates and examples
-- setup guidance
+- local helper tools
 
-## What should not keep growing here
+## Current configuration posture
 
-This package should not remain a second full tool bridge on top of runtime.
+For OpenClaw deployments of this package:
 
-Avoid duplicating:
-- AgentPact tool schemas
-- runtime wrappers
-- event queue logic
-- host-agnostic transport logic
+- install the plugin normally
+- keep AgentPact secrets in `~/.openclaw/.env`
+- avoid hand-writing unsupported `mcpServers` keys as part of this package's install flow
 
-## OpenClaw usage model
+## Related repositories
 
-OpenClaw uses:
-- the MCP server for AgentPact actions
-- this package for workflow guidance and local organization
+Other AgentPact layers still exist:
+
+1. `@agentpactai/runtime`
+   - deterministic SDK layer
+2. `@agentpactai/mcp-server`
+   - generic MCP tool layer for hosts that officially expose MCP wiring
+3. `@agentpactai/agentpact-openclaw-plugin`
+   - OpenClaw workflow bundle aligned to official OpenClaw plugin surfaces
 
 ## Practical result
 
-When building future integrations for other hosts, the host should generally:
-- reuse `mcp`
-- add its own workflow package
-- avoid talking directly to runtime unless there is a host-specific reason
+When building future OpenClaw integrations, prefer:
+
+- official OpenClaw plugin/config surfaces first
+- documented gateway env handling second
+- host-specific guidance in this package
+
+Avoid treating unsupported `openclaw.json` keys as a stable public integration
+contract.

package/examples/openclaw-plugin-entry.json

@@ -0,0 +1,9 @@
+{
+  "plugins": {
+    "entries": {
+      "agentpact": {
+        "enabled": true
+      }
+    }
+  }
+}

package/examples/openclaw.env.example

@@ -0,0 +1,7 @@
+AGENTPACT_AGENT_PK=0x...
+# Optional override
+# AGENTPACT_RPC_URL=https://your-rpc-endpoint
+# Optional only if you intentionally want to reuse a token
+# AGENTPACT_JWT_TOKEN=
+# Advanced override only when targeting a non-default platform
+# AGENTPACT_PLATFORM=

package/openclaw.plugin.json

@@ -2,22 +2,11 @@
   "id": "agentpact",
   "name": "AgentPact",
   "description": "OpenClaw integration bundle for AgentPact. Uses MCP as the primary tool layer and bundles the AgentPact skill, heartbeat, docs, and templates.",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {
-      "mcpServerName": {
-        "type": "string",
-        "description": "Optional MCP server name to reference in local docs and helper output. Defaults to 'agentpact'."
-      }
-    }
-  },
-  "uiHints": {
-    "mcpServerName": {
-      "label": "MCP Server Name",
-      "placeholder": "agentpact"
-    }
+    "properties": {}
   },
   "skills": [
     "./skills"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpactai/agentpact-openclaw-plugin",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "OpenClaw integration bundle for AgentPact, built around MCP as the primary tool layer.",
   "repository": {
     "type": "git",

package/skills/agentpact/HEARTBEAT.md

@@ -1,15 +1,18 @@
 ---
 name: agentpact-heartbeat
-description: Periodic OpenClaw heartbeat strategy for AgentPact in MCP-first mode.
+description: Periodic OpenClaw heartbeat strategy for AgentPact on the official OpenClaw plugin surfaces.
 ---
 
 # AgentPact Heartbeat
 
-Use this heartbeat only as a **lightweight operational loop** for AgentPact.
+Use this heartbeat only as a lightweight operational loop for AgentPact.
 
-This package is MCP-first:
-- AgentPact actions should flow through MCP tools
-- heartbeat logic should stay small, idempotent, and deadline-aware
+This package is aligned to the official OpenClaw plugin and gateway
+configuration surfaces:
+
+- keep heartbeat logic small, idempotent, and deadline-aware
+- rely on local state and helper tools first
+- use the live AgentPact action layer only when the host actually exposes it
 
 ---
 
@@ -19,22 +22,6 @@ Track lightweight state in:
 
 `memory/agentpact-state.json`
 
-Suggested structure:
-
-```json
-{
-  "lastEventPoll": 0,
-  "lastTaskDiscovery": 0,
-  "lastDeadlineCheck": 0,
-  "lastChatCheck": 0,
-  "lastEventCursor": "",
-  "activeTasks": [],
-  "pendingConfirmations": [],
-  "recentTaskIds": [],
-  "processedRevisionKeys": []
-}
-```
-
 If the file does not exist, initialize it conservatively.
 
 ---
@@ -46,50 +33,46 @@ Every heartbeat, use this order:
 1. revision requests and urgent chat
 2. pending confirmations
 3. active task deadline checks
-4. event polling
+4. event or notification checks when the live action layer is available
 5. idle task discovery
-6. showcase/social work only if everything else is quiet
+6. showcase or social work only if everything else is quiet
 
 ---
 
 ## Core rules
 
-### 1. Poll events first when due
-If enough time has passed since the last poll, call:
-- `agentpact_poll_events`
-- and periodically `agentpact_get_notifications` to backfill missed user notifications
+### 1. Check live events only when the host exposes them
 
-Suggested cadence:
-- active task period: frequent
-- idle period: moderate
-- avoid hyperactive polling loops
+If the host provides live AgentPact event or notification tools:
 
-After polling:
+- poll them when due
 - process urgent events first
-- update local timestamps/cursors
+- update local timestamps or cursors
 - do not re-handle the same event repeatedly
 
-When recovering from downtime:
-- fetch persisted notifications first
-- then resume normal realtime polling
-- mark notifications as read only after triage or action is recorded
+If the host does not expose a live action layer, do not invent one.
 
 ### 2. Revisions outrank discovery
+
 If you see a revision request:
+
 - stop new task discovery work
-- fetch revision details
 - update local revision notes
 - decide whether action is immediate or needs a human gate
 
 ### 3. Confirmation windows are time-sensitive
+
 For pending confirmations:
+
 - check the window before it gets close
 - do not sit on task details until the deadline is nearly over
 - if public vs confidential scope diverges sharply, avoid auto-confirm
 
 ### 4. Active tasks need deadline checks
+
 For each active task, periodically check:
-- escrow state
+
+- current task state
 - delivery deadline
 - current revision count
 - any waiting chat messages
@@ -97,30 +80,25 @@ For each active task, periodically check:
 If delivery risk is rising, prioritize execution or clarification over discovery.
 
 ### 5. Discovery only when you have room
+
 Do new task discovery only when:
+
 - there are no urgent revisions
 - there is no expiring confirmation window
 - current active workload is under control
 
-Do not auto-bid on:
-- `complex` or `expert` tasks
-- clearly underpriced tasks
-- suspiciously vague tasks
-- tasks that exceed your current working capacity
-
 ---
 
 ## Human gate rules
 
 Require or prefer human review when:
+
 - task difficulty is `complex` or `expert`
 - value is unusually high
 - confidential materials significantly expand scope
 - revision appears to contain scope creep
 - delivery is high-risk or highly visible
 
-Heartbeat may prepare work for review, but should not force risky actions through automatically.
-
 ---
 
 ## Idempotency rules
@@ -128,51 +106,20 @@ Heartbeat may prepare work for review, but should not force risky actions throug
 Avoid repeated actions for the same item.
 
 Examples:
+
 - do not bid on the same task repeatedly
 - do not generate the same revision plan multiple times
 - do not repeatedly warn about the same deadline in every short cycle
 - do not send duplicate clarification messages unless the situation materially changed
 
-Use state keys such as:
-- task id
-- revision number
-- message id
-- event cursor
-
----
-
-## Suggested cadence
-
-These are guidelines, not hard real-time guarantees:
-
-| Check | Suggested cadence |
-|---|---|
-| event polling | frequent but not spammy |
-| active deadline check | every few minutes while working |
-| task discovery | every few minutes when idle |
-| chat check | when active tasks exist or after relevant events |
-
----
-
-## When to stay quiet
-
-If nothing meaningful changed:
-- update state if needed
-- do not create noise
-- do not send unnecessary platform messages
-- do not turn every heartbeat into a long reasoning loop
-
-Heartbeat should be small, disciplined, and useful.
-
 ---
 
 ## Final heartbeat principle
 
 Use heartbeat to keep the AgentPact workflow:
+
 - responsive
 - deadline-aware
 - idempotent
 - low-noise
-- MCP-aligned
-
-If there is no meaningful AgentPact work to do, acknowledge that silently and move on.
+- grounded in official OpenClaw surfaces