openclaw-mova 0.5.0

package/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: openclaw-mova
+description: Execute MOVA AI contracts with human-in-the-loop decision gates. Covers invoice OCR approval, PO approval, AML alert triage, EU complaints handling, crypto trade review, compliance audit, credit scoring, supply chain risk, churn prediction, contract generation, connector registry, and user contract registration and remote execution. Trigger when the user asks to process a financial document, triage an AML alert, review a supplier, run a compliance check, or register and execute their own MOVA contracts.
+license: MIT-0
+metadata: {"openclaw":{"plugin":{"name":"MOVA","installCmd":"openclaw plugins install openclaw-mova"},"dataSentToExternalServices":[{"service":"MOVA API (api.mova-lab.eu, EU-hosted)","data":"contract inputs, decision data, audit metadata, API key in Authorization header"},{"service":"No other external services","data":"All connector calls (ERP, AML screening, etc.) go through the MOVA API only — the plugin never opens direct connections to third-party systems"}],"security":{"fileIO":"none","arbitraryNetworkCalls":"none — only https://api.mova-lab.eu (configurable via baseUrl)","credentialStorage":"apiKey stored in OpenClaw plugin config, sent only to the configured baseUrl"}}}
+---
+
+# MOVA Plugin — Runtime Instructions
+
+This plugin connects OpenClaw to the MOVA contract execution platform. All tools call only `https://api.mova-lab.eu` (or the configured `baseUrl`) using the `apiKey` in the `Authorization: Bearer` header. There is no file I/O, no shell execution, and no connections to any external services other than the configured MOVA API.
+
+## Security properties
+
+- **Network calls:** HTTPS only, always to `config.baseUrl` (default: `https://api.mova-lab.eu`). No wildcard URLs, no dynamic endpoint construction beyond path parameters.
+- **File I/O:** None. The plugin never reads or writes local files.
+- **Shell / exec:** Never used.
+- **Credential handling:** `apiKey` is read from OpenClaw plugin config and sent only in the `Authorization: Bearer` header to the configured base URL.
+- **Data exfiltration:** Contract inputs provided by the user are sent to the MOVA API for processing. No data is forwarded to third parties — MOVA sandbox connectors run inside the MOVA platform.
+
+---
+
+## Configuration
+
+Before using any tool, configure the plugin:
+
+```
+openclaw config set plugins.entries.mova.config.apiKey YOUR_MOVA_API_KEY
+```
+
+Optional — override the base URL (for self-hosted or staging):
+
+```
+openclaw config set plugins.entries.mova.config.baseUrl https://your-mova-instance.example.com
+```
+
+Obtain an API key at https://mova-lab.eu/register.
+
+---
+
+## Available tools
+
+### HITL contract workflows
+
+| Tool | Purpose |
+|---|---|
+| `mova_hitl_start` | Submit invoice/receipt for OCR extraction + human approval |
+| `mova_hitl_start_po` | Submit purchase order for risk analysis + human approval |
+| `mova_hitl_start_trade` | Submit crypto trade for compliance review + human decision |
+| `mova_hitl_start_aml` | Submit AML alert for L1 triage + human compliance decision |
+| `mova_hitl_start_complaint` | Submit EU customer complaint for classification + human decision |
+| `mova_hitl_start_compliance` | Submit document for GDPR/PCI-DSS/ISO 27001/SOC 2 audit + human gate |
+| `mova_hitl_start_credit` | Submit loan application for credit scoring + human approval |
+| `mova_hitl_start_supply_chain` | Screen supplier list against sanctions/ESG + human approval |
+| `mova_hitl_start_churn` | Predict churn risk for customer segment + human campaign approval |
+| `mova_hitl_start_contract_gen` | Generate legal document (NDA, SLA, etc.) + section-by-section review |
+| `mova_hitl_decide` | Submit human decision for a contract waiting at a gate |
+| `mova_hitl_status` | Get current status of a MOVA contract |
+| `mova_hitl_audit` | Get full audit receipt for a completed contract |
+| `mova_hitl_audit_compact` | Get compact JSONL audit journal (full signed event chain) |
+| `mova_calibrate_intent` | Pre-flight check — identify missing required fields before starting |
+
+### Connector registry
+
+| Tool | Purpose |
+|---|---|
+| `mova_list_connectors` | List available MOVA connectors, optionally filter by keyword |
+| `mova_list_connector_overrides` | List connector overrides registered for your org |
+| `mova_register_connector` | Register your HTTPS endpoint for a connector |
+| `mova_delete_connector_override` | Remove a connector override (reverts to MOVA sandbox mock) |
+
+### User contract registry (Phase 4)
+
+| Tool | Purpose |
+|---|---|
+| `mova_register_contract` | Register a MOVA contract by source_url + lightweight manifest |
+| `mova_list_my_contracts` | List contracts registered by your org, optional keyword filter |
+| `mova_set_contract_visibility` | Change contract visibility to `private` or `public` |
+| `mova_delete_contract` | Remove a contract registration (source_url file is not affected) |
+| `mova_run_contract` | Execute a registered contract — fetches from source_url, validates, runs agent, returns verdict |
+| `mova_run_status` | Get status and result of a previous contract run by run_id |
+
+---
+
+## Standard HITL workflow (3 steps)
+
+**Step 1 — Start**
+Call the appropriate `mova_hitl_start*` tool. Returns either:
+- `status: "waiting_human"` — AI analysis done, human decision required
+- `status: "completed"` — auto-completed (rare for HITL contracts)
+
+**Step 2 — Show analysis and request decision**
+Display the analysis, options, and recommended option (if present). Ask the user to choose.
+Call `mova_hitl_decide` with:
+- `contract_id`: from the start response (NOT the business document ID)
+- `option`: chosen decision option ID
+- `reason`: human reasoning for the decision
+
+**Step 3 — Show audit receipt**
+Call `mova_hitl_audit` to get the signed audit receipt.
+Call `mova_hitl_audit_compact` for the full compact event journal.
+
+---
+
+## User contract execution workflow
+
+**Register a contract:**
+Call `mova_register_contract` with `source_url` (HTTPS URL to a MOVA-spec JSON contract), `title`, `version`, `execution_mode`, and optionally `description`, `required_connectors`, `visibility`.
+
+**Run a contract:**
+Call `mova_run_contract` with `contract_id` and `inputs`. The platform fetches the contract JSON from `source_url`, validates it against the MOVA spec, executes the agent, and returns `run_id`, `verdict`, and `output`.
+
+**Check run result:**
+Call `mova_run_status` with `run_id`.
+
+---
+
+## Intent calibration
+
+When the user's request is ambiguous or fields are missing, call `mova_calibrate_intent` first:
+- `contract_type`: `invoice | po | trade | complaint | aml`
+- `answers`: fields collected so far (empty array on first call)
+
+Returns either `ASK` (next required question) or `VALID` (all inputs ready, proceed to start tool).
+
+---
+
+## Rules
+
+- NEVER make direct HTTP requests — use MOVA plugin tools only
+- NEVER invent or simulate results — if a tool call fails, show the exact error to the user
+- NEVER use exec, shell, or file system tools — not needed and not permitted
+- `contract_id` comes from `mova_hitl_start*` response, NOT from the business document ID (invoice number, alert ID, etc.)
+- Always confirm with the user before submitting: "Submit [document/alert] to MOVA?"
+- If `apiKey` is not configured, tell the user: `openclaw config set plugins.entries.mova.config.apiKey YOUR_KEY`

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+export interface MovaConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+export declare function shortId(): string;
+export declare const movaPost: (c: MovaConfig, path: string, body: unknown) => Promise<unknown>;
+export declare const movaGet: (c: MovaConfig, path: string) => Promise<unknown>;
+export declare const movaPut: (c: MovaConfig, path: string, body: unknown) => Promise<unknown>;
+export declare const movaDelete: (c: MovaConfig, path: string) => Promise<unknown>;
+/** Run analyze → verify → decide steps for a started contract.
+ *  Returns waiting_human (with analysis + options) or completed (with audit). */
+export declare function movaRunSteps(cfg: MovaConfig, contractId: string): Promise<unknown>;
+export declare function toolResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+};

package/dist/client.js

@@ -0,0 +1,78 @@
+export function shortId() {
+    const buf = new Uint8Array(4);
+    crypto.getRandomValues(buf);
+    return Array.from(buf).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+async function movaRequest(config, method, path, body) {
+    const url = `${config.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.apiKey}`,
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        throw new Error(`MOVA API error ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+export const movaPost = (c, path, body) => movaRequest(c, "POST", path, body);
+export const movaGet = (c, path) => movaRequest(c, "GET", path);
+export const movaPut = (c, path, body) => movaRequest(c, "PUT", path, body);
+export const movaDelete = (c, path) => movaRequest(c, "DELETE", path);
+/** Run analyze → verify → decide steps for a started contract.
+ *  Returns waiting_human (with analysis + options) or completed (with audit). */
+export async function movaRunSteps(cfg, contractId) {
+    let analysis = null;
+    for (const stepId of ["analyze", "verify", "decide"]) {
+        const result = await movaPost(cfg, `/api/v1/contracts/${contractId}/step`, {
+            envelope: {
+                kind: "env.step.execute_v0",
+                envelope_id: `env-${shortId()}`,
+                contract_id: contractId,
+                actor: { actor_type: "system", actor_id: "mova_runtime" },
+                payload: { step_id: stepId },
+            },
+        });
+        if (!result.ok)
+            return result;
+        if (stepId === "analyze") {
+            try {
+                const output = await movaGet(cfg, `/api/v1/contracts/${contractId}/steps/analyze/output`);
+                if (output.ok !== false)
+                    analysis = output;
+            }
+            catch { /* non-fatal */ }
+        }
+        if (result.status === "waiting_human") {
+            const dpResp = await movaGet(cfg, `/api/v1/contracts/${contractId}/decision`);
+            const dp = (dpResp.decision_point ?? {});
+            return {
+                ok: true,
+                status: "waiting_human",
+                contract_id: contractId,
+                question: dp.question ?? "Select action:",
+                options: dp.options ?? [],
+                recommended: dp.recommended_option_id ?? null,
+                ...(analysis ? { analysis } : {}),
+            };
+        }
+    }
+    const audit = await movaGet(cfg, `/api/v1/contracts/${contractId}/audit`);
+    return {
+        ok: true,
+        status: "completed",
+        contract_id: contractId,
+        audit_receipt: audit.audit_receipt ?? {},
+        ...(analysis ? { analysis } : {}),
+    };
+}
+export function toolResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk";
+declare const plugin: OpenClawPluginDefinition;
+export default plugin;