@agent-pulse/openclaw-skill 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @agent-pulse/openclaw-skill
+
+OpenClaw skill integration for [AgentPulse SDK](https://www.npmjs.com/package/@agent-pulse/sdk) gating. Provides liveness-based gate checks for incoming and outgoing agent requests.
+
+## Install
+
+```bash
+npm install @agent-pulse/openclaw-skill @agent-pulse/sdk
+```
+
+## Usage
+
+```typescript
+import { startup, withGate, getGateStatus } from "@agent-pulse/openclaw-skill";
+
+// Initialize gate from skill YAML config
+const result = await startup({
+  enabled: true,
+  mode: "strict",       // "strict" | "warn" | "log"
+  threshold: "24h",     // liveness threshold
+  chainId: 84532,       // Base Sepolia (default)
+});
+
+if (result.success && result.gate) {
+  // Gate an incoming request
+  const allowed = await result.gate.gateIncoming("0x...");
+
+  // Or use the middleware wrapper
+  const protectedAction = withGate(async (ctx, input) => {
+    // your action logic
+  });
+}
+```
+
+## Gate Modes
+
+| Mode     | On Reject           | On Error            |
+|----------|---------------------|---------------------|
+| `strict` | Throws error (403)  | Throws error (500)  |
+| `warn`   | Logs warning        | Logs, allows        |
+| `log`    | Telemetry only      | Silent, allows      |
+
+## Links
+
+- [AgentPulse SDK](https://www.npmjs.com/package/@agent-pulse/sdk)
+- [Repository](https://github.com/consensus-hq/agent-pulse)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,148 @@
+# OpenClaw Skill - AgentPulse Gate Integration
+
+This OpenClaw skill integrates the AgentPulse SDK for bidirectional gating of agent interactions. It provides liveness verification before allowing skill actions to proceed.
+
+## Overview
+
+The AgentPulse Gate skill enables OpenClaw agents to:
+
+1. **Verify agent liveness** before processing incoming requests
+2. **Check target agent status** before making outgoing calls
+3. **Enforce gating policies** based on configurable modes
+4. **Surface gate status** in orchestrator queries
+
+## Configuration
+
+Add a `gate` block to your skill YAML configuration:
+
+```yaml
+gate:
+  enabled: true
+  mode: strict      # strict | warn | log
+  threshold: 24h    # duration string (e.g., 30m, 1h, 24h, 7d)
+  chainId: 84532    # optional: Base Sepolia (default) or 8453 for Base Mainnet
+  rpcUrl: https://... # optional: custom RPC endpoint
+```
+
+### Gate Modes
+
+| Mode | Behavior |
+|------|----------|
+| `strict` | Reject requests from/to dead agents with hard error |
+| `warn` | Allow all requests, log warnings for dead agents |
+| `log` | Passive telemetry only, no enforcement |
+
+### Threshold Format
+
+The `threshold` field accepts duration strings:
+- `30m` - 30 minutes
+- `1h` - 1 hour
+- `24h` - 24 hours
+- `1d` - 1 day
+- `7d` - 7 days
+
+## Skill Startup Hook
+
+The skill automatically initializes the AgentPulse SDK on startup:
+
+1. Reads gate configuration from skill YAML
+2. Validates configuration against `gate-schema.json`
+3. Initializes AgentPulseClient with provided settings
+4. Creates AgentPulseGate instance with configured mode
+5. **Gate failure is surfaced** - if RPC is unreachable, skill errors per mode
+
+### Mode Mapping
+
+| Mode | Gate Configuration |
+|------|-------------------|
+| `strict` | `gateIncoming` + `gateOutgoing` with hard reject |
+| `warn` | Gates enabled, warnings logged, requests proceed |
+| `log` | Passive telemetry, all requests proceed |
+
+## Gate Activation Order
+
+```
+1. Skill Startup
+   └── Initialize AgentPulse SDK
+       └── Fail loudly if RPC unreachable (strict/warn)
+
+2. Incoming Request
+   └── gateIncoming(requesterAddr)
+       ├── strict: reject if dead → throw error
+       ├── warn: log warning if dead → proceed
+       └── log: log status → proceed
+
+3. Execute Skill Action/Evaluator
+
+4. Outgoing Request (if applicable)
+   └── gateOutgoing(targetAddr)
+       └── Same behavior as incoming
+```
+
+## Status Output
+
+The skill adds a `gate` section to skill status for orchestrator queries:
+
+```json
+{
+  "gate": {
+    "enabled": true,
+    "mode": "strict",
+    "threshold": "24h",
+    "status": "active",
+    "lastCheck": 1707254400,
+    "agentsChecked": 42,
+    "agentsRejected": 3
+  }
+}
+```
+
+## API
+
+### `gateIncoming(requesterAddr: Address): Promise<boolean>`
+
+Check if an incoming request from `requesterAddr` should be allowed.
+
+- Returns `true` if allowed
+- Throws `AgentPulseError` in strict mode if agent is dead
+- Logs and returns `true` in warn/log modes
+
+### `gateOutgoing(targetAddr: Address): Promise<boolean>`
+
+Check if an outgoing request to `targetAddr` should be allowed.
+
+- Same behavior as `gateIncoming`
+
+### `getGateStatus(): GateStatus`
+
+Get current gate status for monitoring.
+
+## CLI Commands
+
+The skill provides shell scripts for CLI interaction with the AgentPulse protocol:
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `attest.sh` | `./attest.sh <addr> <outcome> [--task-id <id>]` | Submit a peer attestation |
+| `reputation.sh` | `./reputation.sh <addr> [--format json]` | Show composite reputation score and stats |
+| `check.sh` | `./check.sh <addr> --min-score <n>` | Verify if an agent meets a reputation threshold |
+| `attestations.sh` | `./attestations.sh <addr> --received\|--given` | List historical attestations |
+
+Note: In the final distribution, these are aliased to `agent-pulse <command>`.
+
+## Error Handling
+
+If the AgentPulse SDK fails to initialize (bad RPC, network issues):
+
+- **strict mode**: Skill startup fails with error
+- **warn mode**: Warning logged, skill continues without gating
+- **log mode**: Silent failure, passive mode disabled
+
+## Integration Example
+
+See `example-gated-skill.yaml` for complete configuration examples.
+
+## Dependencies
+
+- `@agent-pulse/sdk` - AgentPulse protocol SDK
+- `viem` - Ethereum interactions

package/dist/gate-schema.json

@@ -0,0 +1,75 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://agent-pulse.io/schemas/openclaw-gate.json",
+    "title": "OpenClaw AgentPulse Gate Configuration",
+    "description": "Schema for the gate block in OpenClaw skill YAML configurations",
+    "type": "object",
+    "properties": {
+        "enabled": {
+            "type": "boolean",
+            "description": "Whether gating is enabled for this skill",
+            "default": false
+        },
+        "mode": {
+            "type": "string",
+            "enum": ["strict", "warn", "log"],
+            "description": "Gating mode: strict (reject dead agents), warn (allow with warning), log (passive telemetry only)",
+            "default": "strict"
+        },
+        "threshold": {
+            "type": "string",
+            "description": "Duration string specifying the maximum time since last pulse (e.g., '24h', '1d', '30m')",
+            "pattern": "^[0-9]+[smhdw]$",
+            "examples": ["24h", "1d", "30m", "7d"]
+        },
+        "rpcUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Optional RPC URL for AgentPulse SDK connection. Uses default if not specified."
+        },
+        "chainId": {
+            "type": "integer",
+            "description": "Chain ID for the AgentPulse protocol (default: 84532 for Base Sepolia)",
+            "default": 84532
+        },
+        "contracts": {
+            "type": "object",
+            "description": "Optional contract address overrides",
+            "properties": {
+                "pulseToken": {
+                    "type": "string",
+                    "pattern": "^0x[a-fA-F0-9]{40}$",
+                    "description": "PULSE token contract address"
+                },
+                "pulseRegistry": {
+                    "type": "string",
+                    "pattern": "^0x[a-fA-F0-9]{40}$",
+                    "description": "PulseRegistry contract address"
+                }
+            }
+        }
+    },
+    "required": ["enabled"],
+    "if": {
+        "properties": {
+            "enabled": { "const": true }
+        }
+    },
+    "then": {
+        "required": ["mode", "threshold"]
+    },
+    "additionalProperties": false,
+    "examples": [
+        {
+            "enabled": true,
+            "mode": "strict",
+            "threshold": "24h"
+        },
+        {
+            "enabled": true,
+            "mode": "warn",
+            "threshold": "12h",
+            "chainId": 8453
+        }
+    ]
+}

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * OpenClaw Skill - AgentPulse Gate Integration
+ *
+ * Main implementation of the OpenClaw skill framework integration.
+ * Provides startup hook, gate activation, and status reporting.
+ *
+ * @module openclaw-skill
+ */
+import { type Address } from "viem";
+import { AgentPulseGate } from "@agent-pulse/sdk";
+import type { GateConfig, ParsedThreshold, GateRuntimeStatus, GateStats, GateStatusOutput, OpenClawGate as IOpenClawGate, SkillStartupResult } from "./types.js";
+/**
+ * Validate gate configuration against JSON Schema
+ */
+export declare function validateGateConfig(config: unknown): config is GateConfig;
+/**
+ * Parse duration string to seconds
+ * @param threshold - Duration string (e.g., "24h", "30m")
+ * @returns Parsed threshold or null if invalid
+ */
+export declare function parseThreshold(threshold: string): ParsedThreshold | null;
+/**
+ * OpenClaw Gate implementation wrapping AgentPulse SDK
+ */
+declare class OpenClawGate implements IOpenClawGate {
+    private gate;
+    private config;
+    private _status;
+    private _stats;
+    constructor(gate: AgentPulseGate, config: GateConfig);
+    /**
+     * Gate an incoming request
+     * @param requesterAddr - Address of the requesting agent
+     * @returns true if allowed, throws in strict mode if rejected
+     */
+    gateIncoming(requesterAddr: Address): Promise<boolean>;
+    /**
+     * Gate an outgoing request
+     * @param targetAddr - Address of the target agent
+     * @returns true if allowed, throws in strict mode if rejected
+     */
+    gateOutgoing(targetAddr: Address): Promise<boolean>;
+    /**
+     * Internal check implementation
+     */
+    private performCheck;
+    /**
+     * Get current gate status
+     */
+    getStatus(): GateRuntimeStatus;
+    /**
+     * Get gate statistics
+     */
+    getStats(): GateStats;
+    /**
+     * Get full status output for orchestrator queries
+     */
+    getStatusOutput(): GateStatusOutput;
+}
+/**
+ * Skill startup hook - initializes AgentPulse SDK
+ *
+ * This MUST be called before any skill action/evaluator runs.
+ * Gate initialization failure is surfaced based on mode:
+ * - strict: Throws error, skill startup fails
+ * - warn: Logs warning, continues without gating
+ * - log: Silent, continues without gating
+ *
+ * @param config - Gate configuration from skill YAML
+ * @returns Skill startup result with gate instance
+ */
+export declare function startup(config: unknown): Promise<SkillStartupResult>;
+/**
+ * Middleware that activates gate BEFORE any skill action/evaluator
+ *
+ * Usage in skill definition:
+ * ```typescript
+ * actions: {
+ *   myAction: withGate((ctx, input) => { ... })
+ * }
+ * ```
+ */
+export declare function withGate<TInput, TOutput>(action: (ctx: {
+    gate?: IOpenClawGate;
+}, input: TInput) => Promise<TOutput>, options?: {
+    direction?: "incoming" | "outgoing";
+    address?: Address;
+}): (ctx: {
+    gate?: IOpenClawGate;
+}, input: TInput & {
+    from?: Address;
+    to?: Address;
+}) => Promise<TOutput>;
+/**
+ * Get gate status for orchestrator queries
+ * @param gate - Gate instance (if initialized)
+ * @returns Gate status output
+ */
+export declare function getGateStatus(gate?: IOpenClawGate): GateStatusOutput | null;
+export { OpenClawGate };
+export type { GateConfig, GateStatusOutput, SkillStartupResult };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,MAAM,CAAC;AAC/C,OAAO,EAEL,cAAc,EAIf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,IAAI,aAAa,EAC7B,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAwBpB;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,UAAU,CAIxE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAaxE;AAMD;;GAEG;AACH,cAAM,YAAa,YAAW,aAAa;IACzC,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,MAAM,CAAY;gBAEd,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU;IAsBpD;;;;OAIG;IACG,YAAY,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D;;;;OAIG;IACG,YAAY,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzD;;OAEG;YACW,YAAY;IA+D1B;;OAEG;IACH,SAAS,IAAI,iBAAiB;IAI9B;;OAEG;IACH,QAAQ,IAAI,SAAS;IAIrB;;OAEG;IACH,eAAe,IAAI,gBAAgB;CAepC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsK1E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EACtC,MAAM,EAAE,CAAC,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC1E,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,IAEtD,KAAK;IAAE,IAAI,CAAC,EAAE,aAAa,CAAA;CAAE,EAAE,OAAO,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,OAAO,CAAC,OAAO,CAAC,CAgBjH;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,gBAAgB,GAAG,IAAI,CA2B3E;AAMD,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC"}