openclaw-node-harness 2.0.0

package/skills/n8n/scripts/n8n_api.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+n8n API client for Clawdbot
+Manages workflows, executions, and credentials via n8n REST API
+"""
+
+import os
+import sys
+import json
+import argparse
+import requests
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+
+class N8nClient:
+    """n8n API client"""
+    
+    def __init__(self, base_url: str = None, api_key: str = None):
+        self.base_url = base_url or os.getenv('N8N_BASE_URL')
+        self.api_key = api_key or os.getenv('N8N_API_KEY')
+        
+        if not self.api_key:
+            raise ValueError("N8N_API_KEY not found in environment")
+        
+        self.session = requests.Session()
+        self.session.headers.update({
+            'X-N8N-API-KEY': self.api_key,
+            'Accept': 'application/json',
+            'Content-Type': 'application/json'
+        })
+    
+    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        """Make API request"""
+        url = f"{self.base_url}/api/v1/{endpoint.lstrip('/')}"
+        response = self.session.request(method, url, **kwargs)
+        
+        try:
+            response.raise_for_status()
+            return response.json() if response.content else {}
+        except requests.exceptions.HTTPError as e:
+            error_msg = f"HTTP {response.status_code}: {response.text}"
+            raise Exception(error_msg) from e
+    
+    # Workflows
+    def list_workflows(self, active: bool = None) -> List[Dict]:
+        """List all workflows"""
+        params = {}
+        if active is not None:
+            params['active'] = str(active).lower()
+        return self._request('GET', 'workflows', params=params)
+    
+    def get_workflow(self, workflow_id: str) -> Dict:
+        """Get workflow details"""
+        return self._request('GET', f'workflows/{workflow_id}')
+    
+    def create_workflow(self, workflow_data: Dict) -> Dict:
+        """Create new workflow"""
+        return self._request('POST', 'workflows', json=workflow_data)
+    
+    def update_workflow(self, workflow_id: str, workflow_data: Dict) -> Dict:
+        """Update existing workflow"""
+        return self._request('PATCH', f'workflows/{workflow_id}', json=workflow_data)
+    
+    def delete_workflow(self, workflow_id: str) -> Dict:
+        """Delete workflow"""
+        return self._request('DELETE', f'workflows/{workflow_id}')
+    
+    def activate_workflow(self, workflow_id: str) -> Dict:
+        """Activate workflow"""
+        return self._request('PATCH', f'workflows/{workflow_id}', json={'active': True})
+    
+    def deactivate_workflow(self, workflow_id: str) -> Dict:
+        """Deactivate workflow"""
+        return self._request('PATCH', f'workflows/{workflow_id}', json={'active': False})
+    
+    # Executions
+    def list_executions(self, workflow_id: str = None, limit: int = 20) -> List[Dict]:
+        """List workflow executions"""
+        params = {'limit': limit}
+        if workflow_id:
+            params['workflowId'] = workflow_id
+        return self._request('GET', 'executions', params=params)
+    
+    def get_execution(self, execution_id: str) -> Dict:
+        """Get execution details"""
+        return self._request('GET', f'executions/{execution_id}')
+    
+    def delete_execution(self, execution_id: str) -> Dict:
+        """Delete execution"""
+        return self._request('DELETE', f'executions/{execution_id}')
+    
+    # Manual execution
+    def execute_workflow(self, workflow_id: str, data: Dict = None) -> Dict:
+        """Manually trigger workflow execution"""
+        payload = {'workflowId': workflow_id}
+        if data:
+            payload['data'] = data
+        return self._request('POST', f'workflows/{workflow_id}/execute', json=payload)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='n8n API Client')
+    parser.add_argument('action', choices=[
+        'list-workflows', 'get-workflow', 'activate', 'deactivate',
+        'list-executions', 'get-execution', 'execute'
+    ])
+    parser.add_argument('--id', help='Workflow or execution ID')
+    parser.add_argument('--active', type=lambda x: x.lower() == 'true', help='Filter by active status')
+    parser.add_argument('--limit', type=int, default=20, help='Limit results')
+    parser.add_argument('--data', help='JSON data for execution')
+    parser.add_argument('--pretty', action='store_true', help='Pretty print JSON output')
+    
+    args = parser.parse_args()
+    
+    try:
+        client = N8nClient()
+        result = None
+        
+        if args.action == 'list-workflows':
+            result = client.list_workflows(active=args.active)
+        elif args.action == 'get-workflow':
+            if not args.id:
+                raise ValueError("--id required for get-workflow")
+            result = client.get_workflow(args.id)
+        elif args.action == 'activate':
+            if not args.id:
+                raise ValueError("--id required for activate")
+            result = client.activate_workflow(args.id)
+        elif args.action == 'deactivate':
+            if not args.id:
+                raise ValueError("--id required for deactivate")
+            result = client.deactivate_workflow(args.id)
+        elif args.action == 'list-executions':
+            result = client.list_executions(workflow_id=args.id, limit=args.limit)
+        elif args.action == 'get-execution':
+            if not args.id:
+                raise ValueError("--id required for get-execution")
+            result = client.get_execution(args.id)
+        elif args.action == 'execute':
+            if not args.id:
+                raise ValueError("--id required for execute")
+            data = json.loads(args.data) if args.data else None
+            result = client.execute_workflow(args.id, data=data)
+        
+        # Output
+        if args.pretty:
+            print(json.dumps(result, indent=2))
+        else:
+            print(json.dumps(result))
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/n8n-workflow-automation/.clawhub/origin.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "registry": "https://clawhub.ai",
+  "slug": "n8n-workflow-automation",
+  "installedVersion": "1.0.0",
+  "installedAt": 1770236250992
+}

package/skills/n8n-workflow-automation/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: n8n-workflow-automation
+description: "Design and output n8n workflow JSON with triggers, idempotency, error handling, logging, retries, and human-in-the-loop review queues. Use when you need an auditable n8n automation that won’t silently fail."
+triggers:
+  - "build an n8n workflow"
+  - "create an n8n automation"
+  - "add error handling to this n8n flow"
+  - "make this n8n workflow idempotent"
+negative_triggers:
+  - "write a bash script to automate this"
+  - "set up a CI/CD pipeline"
+  - "build a growth loop"
+---
+
+# n8n workflow automation with retries, logging, and review queues
+
+## PURPOSE
+Designs and outputs n8n workflow JSON with robust triggers, idempotency, error handling, logging, retries, and human-in-the-loop review queues.
+
+## WHEN TO USE
+- TRIGGERS:
+  - Build an n8n workflow that runs every Monday and emails the compliance summary.
+  - Add error handling and retries to this workflow, plus a review queue for failures.
+  - Create a webhook workflow that logs every run and writes a status row to a tracker.
+  - Make this n8n flow idempotent so it does not duplicate records when it reruns.
+  - Instrument this workflow with audit logs and a human approval step.
+- DO NOT USE WHEN…
+  - You need code-only automation without n8n (use a scripting/CI skill).
+  - You need to bypass security controls or hide audit trails.
+  - You need to purchase or recommend prohibited items/services.
+
+## INPUTS
+- REQUIRED:
+  - Workflow intent: trigger type + schedule/timezone + success criteria.
+  - Targets: where to write results (email/Drive/Sheet/DB) and required fields.
+- OPTIONAL:
+  - Existing n8n workflow JSON to modify.
+  - Sample payloads / example records.
+  - Definition of dedup keys (what makes a record unique).
+- EXAMPLES:
+  - Cron: Monday 08:00 Europe/London; send summary email + Drive upload
+  - Webhook: receive JSON; route to folders
+
+## OUTPUTS
+- Default (read-only): a workflow design spec (nodes, data contracts, failure modes).
+- If explicitly requested: `workflow.json` (n8n importable JSON) + `runbook.md` (from template).
+Success = workflow is idempotent, logs every run, retries safely, and routes failures to a review queue.
+
+
+## WORKFLOW
+1. Clarify trigger:
+   - Cron/webhook/manual; schedule/timezone; concurrency expectations.
+2. Define data contract:
+   - input schema, required fields, and validation rules.
+3. Design idempotency:
+   - choose dedup key(s) and storage (DB/Sheet) to prevent duplicates on retries.
+4. Add observability:
+   - generate `run_id`, log start/end, store status row and error details.
+5. Implement error handling:
+   - per-node error branches, retry with backoff, and final failure notification.
+6. Add human-in-the-loop (HITL) review queue:
+   - write failed items to a queue (Sheet/DB) and require approval to reprocess.
+7. “No silent failure” gates:
+   - if counts/thresholds fail, stop workflow and alert.
+8. Output:
+   - If asked for JSON: produce importable n8n workflow JSON + runbook.
+9. STOP AND ASK THE USER if:
+   - destination systems are unknown,
+   - no dedup key exists,
+   - credential strategy (env vars) is not specified,
+   - the workflow needs privileged access not yet approved.
+
+
+## OUTPUT FORMAT
+If outputting **n8n workflow JSON**, conform to:
+
+```json
+{
+  "name": "<workflow name>",
+  "nodes": [ { "name": "Trigger", "type": "n8n-nodes-base.cron", "parameters": {}, "position": [0,0] } ],
+  "connections": {},
+  "settings": {},
+  "active": false
+}
+```
+
+Also output `runbook.md` using `assets/runbook-template.md`.
+
+
+## SAFETY & EDGE CASES
+- Read-only by default; only emit workflow JSON when explicitly requested.
+- Do not include secrets in JSON; reference env vars/credential names only.
+- Include audit logging + failure notifications; avoid workflows that can silently drop data.
+- Prefer least privilege: call only required APIs and minimize scopes.
+
+
+## EXAMPLES
+- Input: “Cron every Monday, email compliance summary, retry failures.”  
+  Output: Node map + `workflow.json` with Cron → Fetch → Aggregate → Email, plus error branches to review queue.
+
+- Input: “Webhook that logs runs and writes status row.”  
+  Output: Webhook → Validate → Process → Append status row; on error → log + notify + queue.
+

package/skills/n8n-workflow-automation/assets/runbook-template.md

@@ -0,0 +1,32 @@
+# n8n Workflow Runbook Template
+
+## Purpose
+- What the workflow does and why it exists.
+
+## Triggers
+- Cron / Webhook / Manual
+- Schedule, timezone, and expected frequency.
+
+## Inputs
+- Source systems and credentials (reference env vars only).
+
+## Outputs
+- Where results go (email, Google Sheet/Drive, database), including file naming.
+
+## Idempotency
+- Dedup key:
+- Safe re-run behavior:
+
+## Error handling
+- Retry policy:
+- Failure notifications:
+- Review queue link/location:
+
+## Logging & audit
+- Run ID:
+- What is logged per run:
+- Where logs are stored:
+
+## Operational checks
+- Expected counts/thresholds:
+- “Stop the line” conditions:

package/skills/narrative-designer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: narrative-designer
+description: >
+  Narrative Designer — stub skill.
+  TODO: implement full skill definition.
+version: 0.1.0
+user-invocable: true
+metadata:
+  openclaw:
+    requires:
+      bins: []
+    os:
+      - macos
+      - linux
+---
+
+# Narrative Designer
+
+> **Status: stub** — This skill is referenced by the lore-writer soul but not yet implemented.
+
+## When to use
+
+(To be defined)
+
+## Commands
+
+(To be defined)

package/skills/ontology/.clawhub/origin.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "registry": "https://clawhub.ai",
+  "slug": "ontology",
+  "installedVersion": "0.1.0",
+  "installedAt": 1770236346036
+}

package/skills/ontology/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: ontology
+description: Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
+triggers:
+  - "link X to Y"
+  - "show dependencies for this project"
+  - "create a new entity"
+  - "what do I know about"
+  - "query the knowledge graph"
+negative_triggers:
+  - "save this to my second brain"
+  - "search the web for"
+  - "remember this preference"
+---
+
+# Ontology
+
+A typed vocabulary + constraint system for representing knowledge as a verifiable graph.
+
+## Core Concept
+
+Everything is an **entity** with a **type**, **properties**, and **relations** to other entities. Every mutation is validated against type constraints before committing.
+
+```
+Entity: { id, type, properties, relations, created, updated }
+Relation: { from_id, relation_type, to_id, properties }
+```
+
+## When to Use
+
+| Trigger | Action |
+|---------|--------|
+| "Remember that..." | Create/update entity |
+| "What do I know about X?" | Query graph |
+| "Link X to Y" | Create relation |
+| "Show all tasks for project Z" | Graph traversal |
+| "What depends on X?" | Dependency query |
+| Planning multi-step work | Model as graph transformations |
+| Skill needs shared state | Read/write ontology objects |
+
+## Core Types
+
+```yaml
+# Agents & People
+Person: { name, email?, phone?, notes? }
+Organization: { name, type?, members[] }
+
+# Work
+Project: { name, status, goals[], owner? }
+Task: { title, status, due?, priority?, assignee?, blockers[] }
+Goal: { description, target_date?, metrics[] }
+
+# Time & Place
+Event: { title, start, end?, location?, attendees[], recurrence? }
+Location: { name, address?, coordinates? }
+
+# Information
+Document: { title, path?, url?, summary? }
+Message: { content, sender, recipients[], thread? }
+Thread: { subject, participants[], messages[] }
+Note: { content, tags[], refs[] }
+
+# Resources
+Account: { service, username, credential_ref? }
+Device: { name, type, identifiers[] }
+Credential: { service, secret_ref }  # Never store secrets directly
+
+# Meta
+Action: { type, target, timestamp, outcome? }
+Policy: { scope, rule, enforcement }
+```
+
+## Storage
+
+Default: `memory/ontology/graph.jsonl`
+
+```jsonl
+{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
+{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}
+{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}
+```
+
+Query via scripts or direct file ops. For complex graphs, migrate to SQLite.
+
+## Workflows
+
+### Create Entity
+
+```bash
+python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'
+```
+
+### Query
+
+```bash
+python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
+python3 scripts/ontology.py get --id task_001
+python3 scripts/ontology.py related --id proj_001 --rel has_task
+```
+
+### Link Entities
+
+```bash
+python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001
+```
+
+### Validate
+
+```bash
+python3 scripts/ontology.py validate  # Check all constraints
+```
+
+## Constraints
+
+Define in `memory/ontology/schema.yaml`:
+
+```yaml
+types:
+  Task:
+    required: [title, status]
+    status_enum: [open, in_progress, blocked, done]
+  
+  Event:
+    required: [title, start]
+    validate: "end >= start if end exists"
+
+  Credential:
+    required: [service, secret_ref]
+    forbidden_properties: [password, secret, token]  # Force indirection
+
+relations:
+  has_owner:
+    from_types: [Project, Task]
+    to_types: [Person]
+    cardinality: many_to_one
+  
+  blocks:
+    from_types: [Task]
+    to_types: [Task]
+    acyclic: true  # No circular dependencies
+```
+
+## Skill Contract
+
+Skills that use ontology should declare:
+
+```yaml
+# In SKILL.md frontmatter or header
+ontology:
+  reads: [Task, Project, Person]
+  writes: [Task, Action]
+  preconditions:
+    - "Task.assignee must exist"
+  postconditions:
+    - "Created Task has status=open"
+```
+
+## Planning as Graph Transformation
+
+Model multi-step plans as a sequence of graph operations:
+
+```
+Plan: "Schedule team meeting and create follow-up tasks"
+
+1. CREATE Event { title: "Team Sync", attendees: [p_001, p_002] }
+2. RELATE Event -> has_project -> proj_001
+3. CREATE Task { title: "Prepare agenda", assignee: p_001 }
+4. RELATE Task -> for_event -> event_001
+5. CREATE Task { title: "Send summary", assignee: p_001, blockers: [task_001] }
+```
+
+Each step is validated before execution. Rollback on constraint violation.
+
+## Integration Patterns
+
+### With Causal Inference
+
+Log ontology mutations as causal actions:
+
+```python
+# When creating/updating entities, also log to causal action log
+action = {
+    "action": "create_entity",
+    "domain": "ontology", 
+    "context": {"type": "Task", "project": "proj_001"},
+    "outcome": "created"
+}
+```
+
+### Cross-Skill Communication
+
+```python
+# Email skill creates commitment
+commitment = ontology.create("Commitment", {
+    "source_message": msg_id,
+    "description": "Send report by Friday",
+    "due": "2026-01-31"
+})
+
+# Task skill picks it up
+tasks = ontology.query("Commitment", {"status": "pending"})
+for c in tasks:
+    ontology.create("Task", {
+        "title": c.description,
+        "due": c.due,
+        "source": c.id
+    })
+```
+
+## Quick Start
+
+```bash
+# Initialize ontology storage
+mkdir -p memory/ontology
+touch memory/ontology/graph.jsonl
+
+# Create schema (optional but recommended)
+cat > memory/ontology/schema.yaml << 'EOF'
+types:
+  Task:
+    required: [title, status]
+  Project:
+    required: [name]
+  Person:
+    required: [name]
+EOF
+
+# Start using
+python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'
+python3 scripts/ontology.py list --type Person
+```
+
+## References
+
+- `references/schema.md` — Full type definitions and constraint patterns
+- `references/queries.md` — Query language and traversal examples