machina-cli 0.6.2__tar.gz → 0.7.0__tar.gz

{machina_cli-0.6.2 → machina_cli-0.7.0}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to machina-cli are documented here.
 
+## [0.7.0] - 2026-07-02
+
+### Added
+- **Human approval checkpoints — `machina approvals` + the `compose_approval`/`resolve_approval` nodes.** A workflow that produces something risky or publishable (an AI-written article, a bulk change) can now gate its final action behind a human: it composes an `approval-request` document (title, preview, and the workflow+inputs that should run **if approved**), saves it, and posts the ask to Slack — the request side is three tasks from the `machina-nodes` library (the provisioned `machina-approval-demo` is a copyable example; an actionless request works too, as a pure acknowledgment gate). The human resolves via `machina approvals list / approve / reject`; resolution executes the in-pod `machina-approval-resolve` workflow, so every surface (CLI, Studio, MCP) shares the same logic — approve dispatches the stored action in-pod, reject just records, double-resolution is guarded, and a dispatch failure is recorded and surfaced without un-approving the decision. This is the Pressbox adoption plan's step ② and the Loop-Engineering "keep one door open" checkpoint as a first-class workflow primitive.
+
+## [0.6.3] - 2026-07-02
+
+### Added
+- **`machina-nodes` — a shared action-node library for pod workflows** (`docs/harness-loop-kit/nodes.py`). The Pressbox lesson applied to Machina's own engine: workflows are already data walked by an executor — what was missing was a registry of small, composable action nodes, so a new automation is graph wiring instead of another copy-pasted pyscript (the Slack notify logic had been written twice across the verify kits). Ships two nodes: `slack_notify` (posts a ready-composed text; webhook from the same `slack-notify-config` doc the verifies use) and `github_issue` (opens a GitHub issue; token+repo from a `github-issue-config` doc — **inert until configured**, so it deploys everywhere safely). Every node is best-effort (never raises), inert without config, and composed via task inputs. A `machina-nodes-demo` workflow ships as living documentation of the pattern.
+
 ## [0.6.2] - 2026-07-01
 
 ### Fixed

{machina_cli-0.6.2 → machina_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: machina-cli
-Version: 0.6.2
+Version: 0.7.0
 Summary: CLI for the Machina AI Agent platform
 Project-URL: Homepage, https://machina.gg
 Project-URL: Repository, https://github.com/machina-sports/machina-cli

{machina_cli-0.6.2 → machina_cli-0.7.0}/docs/harness-loop-kit/README.md

@@ -183,6 +183,27 @@ pelo LLM e persistido pra a montagem de contexto do cliente consumir. O agent
 detect → heal → **resolve ids** → persist → repeat. *(Conservador: só links que resolvem a ids
 reais são gravados — o resto fica como órfão.)*
 
+## 6.1 `nodes.py` — biblioteca de nós compartilhados (padrão Pressbox)
+
+Os workflows da Machina já são *dados* (tasks + conditions + `$.get()`), mas cada
+automação nova vinha copiando código de ação (o notify do Slack foi escrito 2x nos
+verifies). **`nodes.py`** provisiona o connector **`machina-nodes`** — um *registry*
+de nós de ação pequenos e compostos no grafo, não no código:
+
+| Nó | Faz | Config |
+| --- | --- | --- |
+| `slack_notify` | posta um texto **já composto** no webhook do pod | doc `slack-notify-config` (o mesmo dos verifies) |
+| `github_issue` | abre issue no GitHub (title/body/labels) | doc `github-issue-config` `{token, repo}` — **inerte até existir** |
+
+Regras de todo nó: **best-effort** (nunca lança — automação acessória não pode derrubar
+o workflow que a carrega), **inerte sem config**, **composição via inputs da task**
+(o workflow compõe; o nó só executa). O workflow `machina-nodes-demo` fica provisionado
+como documentação viva do padrão.
+
+```bash
+CLIENT_API_URL=… API_TOKEN=… python3 docs/harness-loop-kit/nodes.py --run  # provisiona + smoke no Slack
+```
+
 ## 7. Pendências honestas (transparência)
 
 1. **Redeploy do MCP** ([#287](https://github.com/machina-sports/machina-client-api/issues/287)):

machina_cli-0.7.0/docs/harness-loop-kit/nodes.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""
+Machina Nodes — a shared, reusable node library for pod workflows.
+
+The Pressbox lesson applied to Machina's own engine: workflows here are already
+data (tasks + conditions + $.get() templating) walked by an executor — what was
+missing is a REGISTRY of small, composable action nodes, so a new automation is
+graph wiring instead of another copy-pasted pyscript. This kit provisions one
+connector, `machina-nodes`, whose commands are those nodes:
+
+  slack_notify      post a ready-composed text to the pod's Slack webhook.
+                    Resolves the webhook from the `slack-notify-config` document
+                    (same doc surface-verify/context-verify already use) or an
+                    explicit input. No text / no webhook -> clean no-op.
+  github_issue      open a GitHub issue (title/body/labels). Token + default repo
+                    come from a `github-issue-config` document ({token, repo}) or
+                    explicit inputs. INERT until that doc exists -- provisioning
+                    this connector changes nothing until someone drops a token.
+  compose_approval  build an approval request (an `approval-request` document
+                    value + the Slack ask) for content/actions that need a human
+                    before executing -- the "keep one door open" checkpoint as a
+                    node. The CARRIER workflow saves the doc and posts the ask
+                    (see machina-approval-demo); this node only composes.
+  resolve_approval  act on a human's decision: approve -> dispatch the stored
+                    action workflow (in-pod), reject -> just record it. Guarded
+                    against double-resolution. Wired into the provisioned
+                    `machina-approval-resolve` workflow, which any surface (CLI
+                    `machina approvals`, Studio, MCP) executes with
+                    {request_id, decision}.
+
+Design rules every node follows (and future nodes must too):
+  - best-effort: a node NEVER raises -- an automation nicety must never fail
+    the workflow that carries it. Failures return {..., "error": "..."}.
+  - inert by default: missing config -> {"skipped": "..."}, zero side effects.
+  - composition over configuration: nodes take READY inputs (text, title);
+    composing them is the calling workflow's job, in task inputs -- that keeps
+    each node small and every combination possible.
+
+`machina-nodes-demo` (compose-in-inputs -> post) and `machina-approval-demo`
+(compose_approval -> save doc -> slack ask; the approved action itself runs
+machina-nodes-demo) are provisioned as living documentation of the patterns.
+
+Usage:
+    CLIENT_API_URL="https://<org>-<project>.org.machina.gg" \\
+    API_TOKEN="<project X-Api-Token>" \\
+    python3 nodes.py            # provision the connector + demo workflow
+    python3 nodes.py --run      # provision + post one marked smoke message
+    python3 nodes.py --teardown # remove
+"""
+
+import json
+import os
+import sys
+
+import urllib.request
+import urllib.error
+
+BASE = os.environ.get("CLIENT_API_URL", "").rstrip("/")
+TOKEN = os.environ.get("API_TOKEN", "")
+
+
+def _req(method, path, body=None):
+    url = f"{BASE}/{path.lstrip('/')}"
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method,
+                                 headers={"X-Api-Token": TOKEN, "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read() or "{}")
+    except urllib.error.HTTPError as e:
+        return {"status": False, "error": {"message": f"HTTP {e.code}: {e.read()[:200]}"}}
+    except Exception as e:  # noqa: BLE001
+        return {"status": False, "error": {"message": str(e)}}
+
+
+def _delete_by_name(kind, name):
+    d = _req("GET", f"{kind}/{name}").get("data", {})
+    if isinstance(d, dict) and d.get("_id"):
+        _req("DELETE", f"{kind}/{d['_id']}")
+
+
+def _create(kind, body):
+    _delete_by_name(kind, body["name"])
+    res = _req("POST", kind, body)
+    ok = res.get("status") in (True, "success")
+    print(f"  {'OK ' if ok else 'ERR'} {kind}/{body['name']}"
+          + ("" if ok else f"  -> {json.dumps(res.get('error'))[:120]}"))
+    return ok
+
+
+NODES_SRC = r'''"""machina-nodes: small, composable action nodes for pod workflows."""
+import json, os, urllib.request, urllib.error
+
+
+def _config_doc(name):
+    """Read a single config document's value by name; {} when absent/unreadable."""
+    try:
+        from core.document.controller import document_search
+        r = document_search(filters={"name": name}, page=1, page_size=1)
+        dd = r.get("data") if isinstance(r, dict) else None
+        rows = dd.get("data") if isinstance(dd, dict) else (dd if isinstance(dd, list) else [])
+        if rows:
+            return rows[0].get("value") or {}
+    except Exception:
+        pass
+    return {}
+
+
+def slack_notify(request_data: dict) -> dict:
+    """Post a ready-composed text to Slack. Webhook: explicit input, else the pod's
+    slack-notify-config document. No text / unresolved template / no webhook -> no-op.
+    Best-effort: never raises."""
+    p = request_data.get("params", {}) or request_data
+    text = (p.get("text") or "").strip()
+    if not text or text.startswith("$"):
+        return {"status": True, "data": {"notified": False, "skipped": "no text"}}
+    webhook = (p.get("webhook_url") or "").strip()
+    if not webhook or webhook.startswith("$"):
+        webhook = (_config_doc("slack-notify-config").get("webhook_url") or "").strip()
+    if not webhook:
+        return {"status": True, "data": {"notified": False, "skipped": "no webhook configured"}}
+    try:
+        req = urllib.request.Request(webhook, data=json.dumps({"text": text}).encode(),
+                                     method="POST", headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=15) as r:
+            r.read()
+        return {"status": True, "data": {"notified": True}}
+    except Exception as e:
+        return {"status": True, "data": {"notified": False, "error": str(e)[:150]}}
+
+
+def github_issue(request_data: dict) -> dict:
+    """Open a GitHub issue. Token + default repo come from the github-issue-config
+    document ({token, repo}) or explicit inputs -- INERT until configured. Repo is
+    "owner/name". Best-effort: never raises."""
+    p = request_data.get("params", {}) or request_data
+    title = (p.get("title") or "").strip()
+    if not title or title.startswith("$"):
+        return {"status": True, "data": {"filed": False, "skipped": "no title"}}
+    token = (p.get("token") or "").strip()
+    repo = (p.get("repo") or "").strip()
+    if not token or not repo or repo.startswith("$"):
+        cfg = _config_doc("github-issue-config")
+        token = token if token and not token.startswith("$") else (cfg.get("token") or "").strip()
+        repo = repo if repo and not repo.startswith("$") else (cfg.get("repo") or "").strip()
+    if not token or not repo:
+        return {"status": True, "data": {"filed": False, "skipped": "not configured (github-issue-config)"}}
+    payload = {"title": title, "body": p.get("body") or ""}
+    labels = p.get("labels")
+    if isinstance(labels, list) and labels:
+        payload["labels"] = labels
+    try:
+        req = urllib.request.Request(
+            "https://api.github.com/repos/%s/issues" % repo,
+            data=json.dumps(payload).encode(), method="POST",
+            headers={"Authorization": "Bearer " + token,
+                     "Accept": "application/vnd.github+json",
+                     # GitHub's API rejects requests without a User-Agent.
+                     "User-Agent": "machina-nodes",
+                     "Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=20) as r:
+            d = json.loads(r.read() or "{}")
+        return {"status": True, "data": {"filed": True, "issue_url": d.get("html_url"),
+                                          "number": d.get("number")}}
+    except Exception as e:
+        return {"status": True, "data": {"filed": False, "error": str(e)[:150]}}
+
+
+def compose_approval(request_data: dict) -> dict:
+    """Build an approval request: the `approval-request` document value + the Slack ask.
+    Pure composition -- the carrier workflow saves the doc and posts the text (see the
+    machina-approval-demo graph). action_workflow/action_inputs describe what runs IF a
+    human approves; nothing executes here."""
+    import uuid
+    from datetime import datetime, timezone
+    p = request_data.get("params", {}) or request_data
+    title = (p.get("title") or "").strip()
+    if not title or title.startswith("$"):
+        return {"status": True, "data": {"composed": False, "skipped": "no title"}}
+    request_id = uuid.uuid4().hex[:10]
+    preview = str(p.get("preview") or "")[:2000]
+    action_workflow = (p.get("action_workflow") or "").strip()
+    action_inputs = p.get("action_inputs") if isinstance(p.get("action_inputs"), dict) else {}
+    approval = {"request_id": request_id, "title": title, "preview": preview,
+                "action": {"workflow": action_workflow, "inputs": action_inputs},
+                "status": "pending", "requested_by": p.get("requested_by") or "workflow",
+                "requested_at": datetime.now(timezone.utc).isoformat()}
+    lines = [":raised_hand: *Approval requested* (`%s`)" % request_id, ">*%s*" % title]
+    if preview:
+        lines.append(">%s" % preview[:600].replace("\n", "\n>"))
+    lines.append(">Approve: `machina approvals approve %s` . Reject: `machina approvals reject %s`"
+                 % (request_id, request_id))
+    return {"status": True, "data": {"composed": True, "approval": approval,
+                                      "slack_text": "\n".join(lines)}}
+
+
+def resolve_approval(request_data: dict) -> dict:
+    """Act on a human decision for an approval request. approve -> dispatch the stored
+    action workflow in-pod; reject -> just record. Guarded against double-resolution.
+    Returns the updated doc value for the carrier workflow's document-update task --
+    this node does not write documents itself."""
+    from datetime import datetime, timezone
+    p = request_data.get("params", {}) or request_data
+    request_id = (p.get("request_id") or "").strip()
+    decision = (p.get("decision") or "").strip().lower()
+    if not request_id or request_id.startswith("$"):
+        return {"status": True, "data": {"resolved": False, "error": "no request_id"}}
+    if decision not in ("approve", "reject"):
+        return {"status": True, "data": {"resolved": False, "error": "decision must be approve|reject"}}
+
+    doc_id, value = None, None
+    try:
+        from core.document.controller import document_search
+        r = document_search(filters={"name": "approval-request", "value.request_id": request_id},
+                             page=1, page_size=1)
+        dd = r.get("data") if isinstance(r, dict) else None
+        rows = dd.get("data") if isinstance(dd, dict) else (dd if isinstance(dd, list) else [])
+        if rows:
+            doc_id = rows[0].get("_id")
+            value = rows[0].get("value") or {}
+    except Exception as e:
+        return {"status": True, "data": {"resolved": False, "error": "lookup failed: %s" % str(e)[:120]}}
+    if not doc_id:
+        return {"status": True, "data": {"resolved": False, "error": "request %s not found" % request_id}}
+    if value.get("status") != "pending":
+        return {"status": True, "data": {"resolved": False,
+                                          "skipped": "already %s" % value.get("status")}}
+
+    dispatch = {"dispatched": False}
+    if decision == "approve":
+        action = value.get("action") or {}
+        wf = (action.get("workflow") or "").strip()
+        if wf:
+            token = os.environ.get("MACHINA_PROJECT_KEY", "")
+            try:
+                req = urllib.request.Request("http://localhost:5003/workflow/execute/" + wf,
+                    data=json.dumps(action.get("inputs") or {}).encode(), method="POST",
+                    headers={"X-Api-Token": token, "Content-Type": "application/json"})
+                with urllib.request.urlopen(req, timeout=60) as r:
+                    r.read()
+                dispatch = {"dispatched": True, "workflow": wf}
+            except Exception as e:
+                # the human approved; record the decision but surface the dispatch failure
+                dispatch = {"dispatched": False, "workflow": wf, "error": str(e)[:150]}
+
+    new_value = dict(value)
+    new_value["status"] = "approved" if decision == "approve" else "rejected"
+    new_value["resolved_at"] = datetime.now(timezone.utc).isoformat()
+    new_value["resolved_by"] = p.get("resolver") or "unknown"
+    new_value["dispatch"] = dispatch
+    icon = ":white_check_mark:" if decision == "approve" else ":no_entry_sign:"
+    note = ""
+    if decision == "approve":
+        note = (" -- action `%s` dispatched" % dispatch.get("workflow")) if dispatch.get("dispatched") \
+            else ((" -- action dispatch FAILED: %s" % dispatch.get("error")) if dispatch.get("workflow") else "")
+    slack_text = "%s *Approval %s* (`%s`) -- %s%s" % (
+        icon, new_value["status"], request_id, value.get("title", ""), note)
+    return {"status": True, "data": {"resolved": True, "doc_id": doc_id, "new_value": new_value,
+                                      "dispatch": dispatch, "slack_text": slack_text}}
+'''
+
+
+APPROVAL_DOC_VAL = "$.get('ap_approval', {})"
+APPROVAL_UPDATED_VAL = "$.get('ap_new_value', {})"
+
+
+def definitions():
+    connector = {"name": "machina-nodes", "title": "Machina Nodes", "status": "active",
+                 "description": "shared action-node registry (slack_notify, github_issue, approvals) for workflow composition",
+                 "filename": "machina_nodes.py", "filetype": "pyscript", "filecontent": NODES_SRC,
+                 "commands": [{"name": "SlackNotify", "value": "slack_notify"},
+                              {"name": "GithubIssue", "value": "github_issue"},
+                              {"name": "ComposeApproval", "value": "compose_approval"},
+                              {"name": "ResolveApproval", "value": "resolve_approval"}]}
+    # Living documentation of the composition pattern: the workflow composes the
+    # message in task INPUTS; the node just posts it. Any workflow can copy this task.
+    demo = {"name": "machina-nodes-demo", "title": "Machina Nodes Demo", "status": "active",
+            "description": "composition demo: compose in inputs -> slack_notify node",
+            "context-variables": {"debugger": {"enabled": True}},
+            "inputs": {"text": "$.get('text', '')"},
+            "outputs": {"notified": "$.get('nd_out', {})", "workflow-status": "'executed'"},
+            "tasks": [
+                {"name": "post", "type": "connector",
+                 "connector": {"command": "slack_notify", "name": "machina-nodes"},
+                 "inputs": {"text": "$.get('text', '')"},
+                 "outputs": {"nd_out": "$"}},
+            ]}
+    # The REQUEST pattern: compose -> save the approval-request doc -> post the ask.
+    # Any producer pipeline copies these three tasks (with its own title/preview/action)
+    # to gate an action behind a human -- the "keep one door open" checkpoint.
+    approval_demo = {
+        "name": "machina-approval-demo", "title": "Machina Approval Demo", "status": "active",
+        "description": "request pattern: compose_approval -> save doc -> slack ask (approved action runs machina-nodes-demo)",
+        "context-variables": {"debugger": {"enabled": True}},
+        "inputs": {"title": "$.get('title', 'Demo approval request')",
+                   "preview": "$.get('preview', 'Approve to post a confirmation message via machina-nodes-demo.')",
+                   "action_workflow": "$.get('action_workflow', 'machina-nodes-demo')",
+                   "action_inputs": "$.get('action_inputs', {'text': ':white_check_mark: approved action executed -- this message was gated behind a human approval.'})"},
+        "outputs": {"request": "$.get('ap_approval', {})", "workflow-status": "'executed'"},
+        "tasks": [
+            {"name": "compose", "type": "connector",
+             "connector": {"command": "compose_approval", "name": "machina-nodes"},
+             "inputs": {"title": "$.get('title')", "preview": "$.get('preview')",
+                        "action_workflow": "$.get('action_workflow')",
+                        "action_inputs": "$.get('action_inputs')"},
+             "outputs": {"ap_approval": "$.get('approval')", "ap_slack": "$.get('slack_text')",
+                         "ap_composed": "$.get('composed', False)"}},
+            {"name": "save-request", "type": "document",
+             "condition": "$.get('ap_composed', False) == True",
+             "config": {"action": "save", "embed-vector": False, "force-update": True},
+             "documents": {"approval-request": APPROVAL_DOC_VAL}},
+            {"name": "ask", "type": "connector",
+             "condition": "$.get('ap_composed', False) == True",
+             "connector": {"command": "slack_notify", "name": "machina-nodes"},
+             "inputs": {"text": "$.get('ap_slack', '')"},
+             "outputs": {"ap_notified": "$"}},
+        ]}
+    # The RESOLVE surface: any client (CLI `machina approvals`, Studio, MCP) executes
+    # this with {request_id, decision, resolver} -- the in-pod logic stays shared.
+    approval_resolve = {
+        "name": "machina-approval-resolve", "title": "Machina Approval Resolve", "status": "active",
+        "description": "resolve an approval request: approve -> dispatch stored action; reject -> record",
+        "context-variables": {"debugger": {"enabled": True}},
+        "inputs": {"request_id": "$.get('request_id', '')", "decision": "$.get('decision', '')",
+                   "resolver": "$.get('resolver', 'unknown')"},
+        "outputs": {"resolved": "$.get('ap_resolved', False)", "dispatch": "$.get('ap_dispatch', {})",
+                    "error": "$.get('ap_error', '')", "workflow-status": "'executed'"},
+        "tasks": [
+            {"name": "resolve", "type": "connector",
+             "connector": {"command": "resolve_approval", "name": "machina-nodes"},
+             "inputs": {"request_id": "$.get('request_id')", "decision": "$.get('decision')",
+                        "resolver": "$.get('resolver')"},
+             "outputs": {"ap_resolved": "$.get('resolved', False)", "ap_doc_id": "$.get('doc_id')",
+                         "ap_new_value": "$.get('new_value', {})", "ap_dispatch": "$.get('dispatch', {})",
+                         "ap_slack": "$.get('slack_text', '')",
+                         "ap_error": "$.get('error', $.get('skipped', ''))"}},
+            {"name": "mark-resolved", "type": "document",
+             "condition": "$.get('ap_resolved', False) == True",
+             "config": {"action": "update", "embed-vector": False, "force-update": True},
+             "filters": {"document_id": "$.get('ap_doc_id')"},
+             "documents": {"approval-request": APPROVAL_UPDATED_VAL}},
+            {"name": "confirm", "type": "connector",
+             "condition": "$.get('ap_resolved', False) == True",
+             "connector": {"command": "slack_notify", "name": "machina-nodes"},
+             "inputs": {"text": "$.get('ap_slack', '')"},
+             "outputs": {"ap_notified": "$"}},
+        ]}
+    return [("connector", connector), ("workflow", demo),
+            ("workflow", approval_demo), ("workflow", approval_resolve)]
+
+
+def main():
+    if not BASE or not TOKEN:
+        sys.exit("Set CLIENT_API_URL and API_TOKEN environment variables.")
+    defs = definitions()
+    if "--teardown" in sys.argv:
+        print(f"Tearing down machina-nodes on {BASE} ...")
+        for kind, body in reversed(defs):
+            _delete_by_name(kind, body["name"])
+            print(f"  removed {kind}/{body['name']}")
+        return
+    print(f"Provisioning machina-nodes on {BASE} ...")
+    ok = all(_create(kind, body) for kind, body in defs)
+    print("Done." if ok else "Done with errors — check output above.")
+    if "--run" in sys.argv:
+        print("\nSmoke: posting one marked message via the demo workflow ...")
+        r = _req("POST", "workflow/execute/machina-nodes-demo",
+                 {"text": ":test_tube: machina-nodes — shared node library is live in this pod "
+                          "(slack_notify + github_issue registered)."})
+        print("  execute status:", r.get("status"), "| error:", r.get("error"))
+
+
+if __name__ == "__main__":
+    main()

{machina_cli-0.6.2 → machina_cli-0.7.0}/docs-site/.vitepress/config.mts

@@ -78,6 +78,7 @@ export default defineConfig({
           text: "Operations",
           items: [
             { text: "execution", link: "/commands/execution" },
+            { text: "approvals", link: "/commands/approvals" },
             { text: "skills", link: "/commands/skills" },
             { text: "factory", link: "/commands/factory" },
             { text: "loop", link: "/commands/loop" },

machina_cli-0.7.0/docs-site/commands/approvals.md

@@ -0,0 +1,63 @@
+# approvals
+
+The `approvals` command group is the **human side of workflow checkpoints** — the "keep one door open" principle as a first-class primitive. A workflow that produces something risky or publishable (an AI-written article, a bulk data change) can **gate the final action behind a human**: it files an approval request and stops. You list what's waiting, read it, and approve or reject. On approve, the stored action runs **in-pod**.
+
+## Usage
+
+```text
+machina approvals list    [--project <id>] [--all] [--json]
+machina approvals approve <request-id> [--project <id>] [--json]
+machina approvals reject  <request-id> [--project <id>] [--json]
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--project`, `-p` | A specific project (defaults to the selected project). |
+| `--all`, `-a` | (`list`) Include already-resolved requests. |
+| `--json`, `-j` | Machine-readable output. |
+
+## The flow
+
+```text
+producer workflow ──> approval-request doc + Slack ask ──> human ──> approve/reject
+                                                                   │
+                                              approve: stored action workflow runs in-pod
+```
+
+1. A producer workflow composes a request with the `compose_approval` node (title, preview, and **what should run if approved** — a workflow name + inputs), saves it as an `approval-request` document, and posts the ask to the pod's Slack channel.
+2. A human sees it (Slack or `approvals list`) and decides.
+3. `approve`/`reject` execute the pod's `machina-approval-resolve` workflow — approve dispatches the stored action; reject just records the decision. Double-resolution is guarded: a request resolves exactly once.
+
+```text
+$ machina approvals list
+
+              Approval requests — pending
+┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ Request    ┃ Title                    ┃ Status  ┃ On approve, runs ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ a1b2c3d4e5 │ Publish: Flamengo x Vasco│ pending │ publish-article  │
+└────────────┴──────────────────────────┴─────────┴──────────────────┘
+
+$ machina approvals approve a1b2c3d4e5
+Request a1b2c3d4e5 approved.
+  action dispatched: publish-article
+```
+
+::: tip Resolution logic lives in the pod, not the CLI
+`approve`/`reject` just execute the `machina-approval-resolve` workflow with `{request_id, decision}`. Any surface — this CLI, the Studio, an MCP agent — resolves through the same workflow, so the guard rails (double-resolution, dispatch recording) are shared.
+:::
+
+## Gating your own workflow
+
+The request side is three tasks from the [`machina-nodes`](https://github.com/machina-sports/machina-cli/blob/main/docs/harness-loop-kit/nodes.py) library (see the provisioned `machina-approval-demo` workflow for a copyable example):
+
+1. `compose_approval` — inputs: `title`, `preview`, `action_workflow`, `action_inputs`.
+2. A `document` save task for the composed `approval-request`.
+3. `slack_notify` with the composed ask.
+
+An **actionless** request (empty `action_workflow`) is also valid — a pure human acknowledgment gate.
+
+## Related
+
+- [`loop`](/commands/loop) — the harness loop's `needs_review` is the same principle at the conversation level; `approvals` brings it to any workflow.
+- Provisioning: `docs/harness-loop-kit/nodes.py` in the [machina-cli repo](https://github.com/machina-sports/machina-cli) (`python3 nodes.py` against the pod).

{machina_cli-0.6.2 → machina_cli-0.7.0}/docs-site/index.md

@@ -67,6 +67,6 @@ machina workflow list
 | --- | --- |
 | **Platform** | `login` · `org` · `project` · `credentials` · `connect` · `mcp` |
 | **Resources** | `workflow` · `agent` · `connector` · `mapping` · `prompt` · `document` |
-| **Operations** | `execution` · `skills` · `factory` · `loop` · `context-graph` · `sports` · `template` · `deploy` · `config` · `update` |
+| **Operations** | `execution` · `approvals` · `skills` · `factory` · `loop` · `context-graph` · `sports` · `template` · `deploy` · `config` · `update` |
 
 New here? Start with [Installation](/guide/installation), then the [Quickstart](/guide/quickstart).

{machina_cli-0.6.2 → machina_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "machina-cli"
-version = "0.6.2"
+version = "0.7.0"
 description = "CLI for the Machina AI Agent platform"
 readme = "README.md"
 requires-python = ">=3.10"

{machina_cli-0.6.2 → machina_cli-0.7.0}/src/machina_cli/__init__.py

@@ -1,3 +1,3 @@
 """Machina CLI - Command line interface for the Machina AI Agent platform."""
 
-__version__ = "0.6.2"
+__version__ = "0.7.0"

machina_cli-0.7.0/src/machina_cli/commands/approvals.py

@@ -0,0 +1,122 @@
+"""Human approvals — the workflow checkpoint door.
+
+Workflows gate risky/publishable actions behind an `approval-request` document
+(composed by the machina-nodes `compose_approval` node). This command group is
+the human side of that door: list what's waiting, approve or reject. Resolution
+runs IN-POD via the `machina-approval-resolve` workflow, so every surface (CLI,
+Studio, MCP) shares the same logic — the CLI is deliberately thin.
+"""
+
+import getpass
+import json as json_lib
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from machina_cli.project_client import ProjectClient
+
+app = typer.Typer(help="Human approvals (list / approve / reject workflow checkpoints)")
+console = Console()
+
+
+def _requests(client: ProjectClient, show_all: bool) -> list:
+    filters = {"name": "approval-request"}
+    if not show_all:
+        filters["value.status"] = "pending"
+    r = client.post(
+        "document/search",
+        {"compact": False, "filters": filters, "page": 1, "page_size": 50, "sorters": ["created", -1]},
+    )
+    d = r.get("data")
+    return (d.get("data") if isinstance(d, dict) else d) or []
+
+
+@app.command("list")
+def list_approvals(
+    project_id: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID (default: selected project)"),
+    show_all: bool = typer.Option(False, "--all", "-a", help="Include already-resolved requests"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """List approval requests waiting for a human (default: pending only)."""
+    client = ProjectClient(project_id)
+    rows = _requests(client, show_all)
+
+    if json_output:
+        payload = [{"request_id": (r.get("value") or {}).get("request_id"),
+                    "title": (r.get("value") or {}).get("title"),
+                    "status": (r.get("value") or {}).get("status"),
+                    "action_workflow": ((r.get("value") or {}).get("action") or {}).get("workflow"),
+                    "requested_at": (r.get("value") or {}).get("requested_at"),
+                    "created": str(r.get("created") or "")} for r in rows]
+        console.print_json(json_lib.dumps(payload, default=str))
+        return
+
+    if not rows:
+        console.print("[green]No pending approvals.[/green]" if not show_all else "[yellow]No approval requests found.[/yellow]")
+        return
+    table = Table(title="Approval requests" + ("" if show_all else " — pending"))
+    table.add_column("Request", style="bold")
+    table.add_column("Title", overflow="fold")
+    table.add_column("Status")
+    table.add_column("On approve, runs", style="dim")
+    table.add_column("Requested", style="dim", no_wrap=True)
+    for r in rows:
+        v = r.get("value") or {}
+        status = v.get("status", "?")
+        color = {"pending": "yellow", "approved": "green", "rejected": "red"}.get(status, "dim")
+        table.add_row(v.get("request_id", "?"), v.get("title", ""),
+                      f"[{color}]{status}[/]", (v.get("action") or {}).get("workflow") or "—",
+                      str(v.get("requested_at") or r.get("created") or "")[:16])
+    console.print(table)
+    console.print("  [dim]Resolve with[/] [bold]machina approvals approve|reject <request-id>[/]")
+
+
+def _resolve(request_id: str, decision: str, project_id: Optional[str], json_output: bool) -> None:
+    client = ProjectClient(project_id)
+    try:
+        resolver = getpass.getuser()
+    except Exception:  # noqa: BLE001
+        resolver = "cli"
+    result = client.post(
+        "workflow/execute/machina-approval-resolve",
+        {"request_id": request_id, "decision": decision, "resolver": resolver},
+    )
+    data = result.get("data") or {}
+    if json_output:
+        console.print_json(json_lib.dumps(data, default=str))
+        return
+    resolved = data.get("resolved")
+    dispatch = data.get("dispatch") or {}
+    error = data.get("error") or ""
+    if resolved is True or (resolved is None and result.get("status")):
+        verb = "approved" if decision == "approve" else "rejected"
+        console.print(f"[green]Request {request_id} {verb}.[/green]")
+        if dispatch.get("dispatched"):
+            console.print(f"  [dim]action dispatched:[/] [bold]{dispatch.get('workflow')}[/]")
+        elif decision == "approve" and dispatch.get("workflow"):
+            console.print(f"  [red]action dispatch failed:[/] {dispatch.get('error')}")
+    else:
+        console.print(f"[red]Could not resolve {request_id}:[/red] {error or 'unknown error'}")
+        raise typer.Exit(1)
+
+
+@app.command("approve")
+def approve(
+    request_id: str = typer.Argument(..., help="The approval request id (from `approvals list` or Slack)"),
+    project_id: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID (default: selected project)"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Approve a request — the stored action workflow runs in-pod."""
+    _resolve(request_id, "approve", project_id, json_output)
+
+
+@app.command("reject")
+def reject(
+    request_id: str = typer.Argument(..., help="The approval request id (from `approvals list` or Slack)"),
+    project_id: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID (default: selected project)"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Reject a request — recorded, nothing runs."""
+    _resolve(request_id, "reject", project_id, json_output)

{machina_cli-0.6.2 → machina_cli-0.7.0}/src/machina_cli/main.py

@@ -8,6 +8,7 @@ from rich.text import Text
 
 from machina_cli import __version__
 from machina_cli.commands import (
+    approvals,
     auth,
     org,
     project,
@@ -60,6 +61,7 @@ CMD_GROUPS = [
         "Operations",
         [
             ("execution", "Executions"),
+            ("approvals", "Human approvals"),
             ("skills", "Skills"),
             ("loop", "Agentic turn loop (harness)"),
             ("factory", "Build apps (Factory)"),
@@ -174,6 +176,7 @@ app.add_typer(agent.app, name="agent", help="Agent management")
 app.add_typer(template.app, name="template", help="Template management")
 app.add_typer(skills.app, name="skills", help="Skills management")
 app.add_typer(execution.app, name="execution", help="Execution management")
+app.add_typer(approvals.app, name="approvals", help="Human approvals (workflow checkpoints)")
 app.add_typer(loop.app, name="loop", help="Durable agentic turn loop (harness)")
 app.add_typer(
     context_graph.app, name="context-graph", help="Self-healing / monitoring status across projects"

{machina_cli-0.6.2 → machina_cli-0.7.0}/src/machina_cli/repl.py

@@ -31,6 +31,7 @@ REPL_COMMANDS = [
     "factory",
     "template",
     "execution",
+    "approvals",
     "credentials",
     "deploy",
     "config",
@@ -94,6 +95,7 @@ SUB_COMMANDS = {
     ],
     "template": ["list", "install", "push"],
     "execution": ["get", "list"],
+    "approvals": ["list", "approve", "reject"],
     "credentials": ["list", "generate", "revoke"],
     "deploy": ["start", "status", "restart"],
     "config": ["list", "set", "get"],
@@ -203,6 +205,7 @@ def _show_help():
             "Operations",
             [
                 ("execution list|get <id>", "Execution history"),
+                ("approvals list|approve|reject <id>", "Human approval checkpoints"),
                 ("skills list|install|info|run|push|constructor", "Skills-first surface"),
                 ("factory run|status|watch|logs|list", "Build apps (Factory coding-agent)"),
                 ("sports <module> <command>", "Sports-skills passthrough"),

machina_cli-0.7.0/tests/test_approvals.py

@@ -0,0 +1,96 @@
+"""Tests for `machina approvals` — the human side of workflow approval checkpoints.
+
+The CLI is deliberately thin: list reads `approval-request` documents; approve/
+reject execute the in-pod `machina-approval-resolve` workflow so every surface
+shares the same resolution logic. These pin that contract.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+from typer.testing import CliRunner
+
+from machina_cli.main import app
+
+runner = CliRunner()
+
+
+def _doc(request_id, title, status="pending", workflow="publish-article"):
+    return {"created": "Thu, 02 Jul 2026 12:00:00 GMT",
+            "value": {"request_id": request_id, "title": title, "status": status,
+                      "action": {"workflow": workflow}, "requested_at": "2026-07-02T12:00:00+00:00"}}
+
+
+def test_list_renders_pending_requests():
+    client = MagicMock()
+    client.post.return_value = {"data": {"data": [_doc("abc123", "Publish: Flamengo preview")]}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "list"])
+    assert result.exit_code == 0
+    assert "abc123" in result.output and "Flamengo" in result.output
+    body = client.post.call_args[0][1]
+    assert body["filters"] == {"name": "approval-request", "value.status": "pending"}
+
+
+def test_list_all_drops_the_status_filter():
+    client = MagicMock()
+    client.post.return_value = {"data": {"data": []}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "list", "--all"])
+    assert result.exit_code == 0
+    assert client.post.call_args[0][1]["filters"] == {"name": "approval-request"}
+
+
+def test_list_json_is_parseable():
+    client = MagicMock()
+    client.post.return_value = {"data": {"data": [_doc("abc123", "T")]}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "list", "--json"])
+    assert result.exit_code == 0
+    payload = json.loads(result.output)
+    assert payload[0]["request_id"] == "abc123"
+    assert payload[0]["action_workflow"] == "publish-article"
+
+
+def test_approve_executes_the_resolve_workflow():
+    client = MagicMock()
+    client.post.return_value = {"status": True, "data": {"resolved": True,
+                                                          "dispatch": {"dispatched": True, "workflow": "publish-article"}}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "approve", "abc123"])
+    assert result.exit_code == 0
+    path, body = client.post.call_args[0]
+    assert path == "workflow/execute/machina-approval-resolve"
+    assert body["request_id"] == "abc123" and body["decision"] == "approve"
+    assert "approved" in result.output and "publish-article" in result.output
+
+
+def test_reject_sends_reject_decision():
+    client = MagicMock()
+    client.post.return_value = {"status": True, "data": {"resolved": True, "dispatch": {"dispatched": False}}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "reject", "abc123"])
+    assert result.exit_code == 0
+    assert client.post.call_args[0][1]["decision"] == "reject"
+    assert "rejected" in result.output
+
+
+def test_resolve_failure_exits_nonzero_with_reason():
+    client = MagicMock()
+    client.post.return_value = {"status": True, "data": {"resolved": False, "error": "request zz not found"}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "approve", "zz"])
+    assert result.exit_code == 1
+    assert "not found" in result.output
+
+
+def test_approve_reports_dispatch_failure():
+    client = MagicMock()
+    client.post.return_value = {"status": True, "data": {"resolved": True,
+                                                          "dispatch": {"dispatched": False, "workflow": "w", "error": "boom"}}}
+    with patch("machina_cli.commands.approvals.ProjectClient", return_value=client):
+        result = runner.invoke(app, ["approvals", "approve", "abc123"])
+    assert result.exit_code == 0
+    assert "dispatch failed" in result.output and "boom" in result.output