procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/webplatform/aat_mcp/chat_surface.yaml

@@ -0,0 +1,372 @@
+# The PUBLISHED chat surface: exactly which PROCESIO operations are offered to a
+# general chat client, under which names, with which public wording.
+#
+# WHY THIS FILE EXISTS. The registry is the source of truth for what a tool IS
+# (Hard rule 3) and server.py rightly tracks it - that surface dispatches whatever
+# exists. A directory listing is a different kind of thing: a contract with people
+# who did not write the manifests. If the published list were derived from them,
+# renaming an action would silently remove a published tool, adding an argument
+# would silently reshape a published schema, and a new tool would silently appear
+# in a surface someone had reviewed. All three are invisible at the moment they
+# happen, which is the worst property a published contract can have.
+#
+# So this file is the source of truth for ONE fact no manifest records: which
+# operations we stand behind publicly, and how they are described to a stranger.
+# It holds no behaviour. When it disagrees with the registry, CI fails
+# (tests/test_chat_surface.py) - deliberately, and at build time.
+#
+# CURATION RULES, applied when adding an entry:
+#   - It serves creating something in PROCESIO, or seeing what you created.
+#   - It is nameable. A tool called "run any action" tells a model nothing and
+#     reads to a reviewer as an unbounded surface.
+#   - Its failure mode is legible. An action that can hang a client does not go
+#     here whatever else it does (see `excluded:` at the bottom).
+#   - `description` is written for someone who has never used PROCESIO. It is NOT
+#     copied from the manifest: manifest text addresses an operator who already
+#     knows the platform, and generating it from there would reintroduce exactly
+#     the coupling this file removes.
+#
+# read_only: true means the call changes nothing, anywhere. A client may run it
+# without asking. It is NOT the same question as the reversibility gate, which
+# asks whether a change can be undone - process-create is reversible and is
+# emphatically not read-only. The gate is still enforced: a conformance test
+# asserts read_only entries are also reversible, so a mislabel cannot widen what
+# runs unattended.
+
+# Semver, and the contract this number describes is the published tool list: names,
+# schemas and wording. Adding a tool is a minor bump, removing or renaming one or
+# tightening a schema is a major bump, and rewording a description is a patch. It is
+# NOT the package version - server.json aligns that with the release - because a
+# client pins to a surface and a release can ship with the surface unchanged.
+surface_version: "0.1.0"
+
+# A tool result goes straight into a model's context, so an unbounded one is a
+# context leak rather than a large answer. Results over the cap are truncated and
+# carry a note telling the caller how to narrow the request, which is more useful
+# to a model than a silently short list. Per-tool `max_response_bytes` overrides.
+limits:
+  max_response_bytes: 60000
+
+# Arguments every PROCESIO action accepts and this surface exposes by default.
+# `profile` is deliberately NOT among them: it selects a local credential profile,
+# which is an installation detail rather than something a chat user should choose.
+common_args:
+  workspace_id:
+    flag: workspace-id
+    type: string
+    description: "Workspace to act in. Omit to use the default workspace."
+  environment:
+    flag: environment
+    type: string
+    description: "Named environment, e.g. Internal-QA. Omit for the default."
+
+tools:
+
+  # --- Pillar 1: Process Designer ------------------------------------------
+  - name: procesio_list_processes
+    pillar: process
+    title: List PROCESIO processes
+    description: >
+      List the automation processes in a PROCESIO workspace, newest first.
+      Use this to find the id of a process before running, editing or validating it.
+    target: {tool: procesio, action: list-processes}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: search, type: string, description: "Only processes whose name matches this text."}
+      - {flag: page, type: integer, description: "1-based page number."}
+      - {flag: page-size, type: integer, expose: page_size, description: "Processes per page."}
+
+  - name: procesio_create_process
+    pillar: process
+    title: Create a PROCESIO process
+    description: >
+      Create a new automation process from a JSON definition of its steps and
+      connections. Returns the new process id. Pass dry_run to see what would be
+      built without creating anything.
+    target: {tool: procesio, action: process-create}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: config, type: string, description: "The process definition, as a JSON object."}
+      - {flag: dry-run, type: boolean, expose: dry_run, description: "Report what would be created; create nothing."}
+
+  - name: procesio_edit_process
+    pillar: process
+    title: Edit a PROCESIO process
+    description: >
+      Change an existing process - add, retarget or reconfigure its steps. Pass
+      dry_run first to see the diff. Removing steps additionally requires
+      allow_remove, so a partial definition cannot silently delete work.
+    target: {tool: procesio, action: process-edit}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The process id."}
+      - {flag: config, type: string, description: "The changes, as a JSON object."}
+      - {flag: dry-run, type: boolean, expose: dry_run, description: "Report the diff; change nothing."}
+      - {flag: allow-remove, type: boolean, expose: allow_remove, description: "Permit this edit to delete steps."}
+
+  - name: procesio_validate_process
+    pillar: process
+    title: Validate a PROCESIO process
+    description: >
+      Check a process for errors without running it - unconnected steps, missing
+      required inputs, broken references. Do this before running a process you
+      just built. Validating is not the same as running: a process can validate
+      and still fail at execution.
+    target: {tool: procesio, action: process-validate}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The process id."}
+
+  - name: procesio_run_process
+    pillar: process
+    title: Run a PROCESIO process
+    description: >
+      Execute a process and return its run id. A process does real work - it can
+      send mail, write to databases and call external systems - so this is never
+      run unattended. Follow it with procesio_get_run_status and procesio_get_run_output.
+    target: {tool: procesio, action: run-process}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The process id."}
+      - {flag: payload, type: string, description: "Input values for the run, as a JSON object."}
+      - {flag: synchronous, type: boolean, description: "Wait for the run to finish instead of returning immediately."}
+      - {flag: timeout, type: integer, description: "Seconds to wait when synchronous."}
+
+  - name: procesio_get_run_status
+    pillar: process
+    title: Check a PROCESIO run
+    description: >
+      Report whether a run is still going, finished or failed, and which step it
+      reached. Takes the run id returned by procesio_run_process.
+    target: {tool: procesio, action: get-instance-status}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The run id."}
+      - {flag: actions, type: boolean, description: "Include per-step detail."}
+
+  - name: procesio_get_run_output
+    pillar: process
+    title: Read a PROCESIO run output
+    description: >
+      Return the values a finished run produced. Only meaningful once the run has
+      completed - check with procesio_get_run_status first.
+    target: {tool: procesio, action: get-instance-output}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The run id."}
+
+  - name: procesio_tidy_process_layout
+    pillar: process
+    title: Tidy a process canvas
+    description: >
+      Re-arrange a process's steps on the design canvas so it is readable. Changes
+      only the visual layout, never what the process does. Worth running after
+      building a process through the API, which places steps without arranging them.
+    target: {tool: procesio, action: relayout-process}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The process id."}
+      - {flag: dry-run, type: boolean, expose: dry_run, description: "Report the new layout; change nothing."}
+
+  # --- Pillar 2: Form Designer ---------------------------------------------
+  - name: procesio_list_forms
+    pillar: form
+    title: List PROCESIO forms
+    description: >
+      List the forms in a workspace. A form is the screen a person fills in to
+      start or feed a process.
+    target: {tool: procesio, action: form-list}
+    read_only: true
+    common: [workspace_id, environment]
+    args: []
+
+  - name: procesio_get_form
+    pillar: form
+    title: Read a PROCESIO form
+    description: >
+      Return a form's definition - its fields, their types and how they are laid out.
+    target: {tool: procesio, action: form-get}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The form id."}
+
+  - name: procesio_create_form
+    pillar: form
+    title: Create a PROCESIO form
+    description: >
+      Create a form from a JSON definition. Returns the new form id. Add fields
+      afterwards with procesio_add_form_field.
+    target: {tool: procesio, action: form-create}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: config, type: string, description: "The form definition, as a JSON object."}
+      - {flag: dry-run, type: boolean, expose: dry_run, description: "Report what would be created; create nothing."}
+
+  - name: procesio_add_form_field
+    pillar: form
+    title: Add fields to a PROCESIO form
+    description: >
+      Add one or more input fields to an existing form.
+    target: {tool: procesio, action: form-add-element}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: id, type: string, required: true, description: "The form id."}
+      - {flag: elements, type: string, description: "The fields to add, as a JSON array."}
+      - {flag: parent, type: string, description: "Id of the container to add them into."}
+      - {flag: dry-run, type: boolean, expose: dry_run, description: "Report what would be added; add nothing."}
+
+  # --- Pillar 3: AI Connector Builder --------------------------------------
+  - name: procesio_build_connector
+    pillar: connector
+    title: Build a PROCESIO connector from API docs
+    description: >
+      Start building a custom PROCESIO connector from an API's documentation. Give
+      it the docs URL and what you need the connector to do; it reads the docs,
+      asks what it still needs, and generates a connector package. Returns a build
+      id - follow it with procesio_get_connector_build.
+    target: {tool: connector-builder, action: create-build}
+    read_only: false
+    common: []
+    args:
+      - {flag: api-url, type: string, expose: api_url, description: "URL of the API documentation to read."}
+      - {flag: api-docs-text, type: string, expose: api_docs_text, description: "The documentation itself, if there is no public URL."}
+      - {flag: user-requirements, type: string, expose: user_requirements, description: "What the connector needs to do, in plain language."}
+
+  - name: procesio_list_connector_builds
+    pillar: connector
+    title: List connector builds
+    description: >
+      List connector builds and their current stage.
+    target: {tool: connector-builder, action: list-builds}
+    read_only: true
+    common: []
+    args:
+      - {flag: status, type: string, description: "Only builds in this stage."}
+      - {flag: page, type: integer, description: "1-based page number."}
+
+  - name: procesio_get_connector_build
+    pillar: connector
+    title: Check a connector build
+    description: >
+      Report a build's stage, what it is waiting on, and whether a connector
+      package is ready to download.
+    target: {tool: connector-builder, action: get-build}
+    read_only: true
+    common: []
+    args:
+      - {flag: build-id, type: string, expose: build_id, required: true, description: "The build id."}
+
+  - name: procesio_download_connector
+    pillar: connector
+    title: Download a built connector
+    description: >
+      Save a finished build's connector package to a local file, ready to install
+      with procesio_install_connector.
+    target: {tool: connector-builder, action: download-artifact}
+    read_only: false
+    common: []
+    args:
+      - {flag: build-id, type: string, expose: build_id, required: true, description: "The build id."}
+      - {flag: out, type: string, required: true, description: "Local path to write the package to."}
+
+  - name: procesio_install_connector
+    pillar: connector
+    title: Install a connector into PROCESIO
+    description: >
+      Install a connector package into a workspace, after which its operations
+      appear as steps you can use when building a process.
+    target: {tool: procesio, action: customaction-upload}
+    read_only: false
+    common: [workspace_id, environment]
+    args:
+      - {flag: file, type: string, required: true, description: "Path to the connector package."}
+      - {flag: name, type: string, description: "Name to show in the designer."}
+
+  - name: procesio_list_connectors
+    pillar: connector
+    title: List installed connectors
+    description: >
+      List the connectors installed in a workspace - the extra step types available
+      when building a process.
+    target: {tool: procesio, action: customaction-list}
+    read_only: true
+    common: [workspace_id, environment]
+    args: []
+
+  # --- Workspace ------------------------------------------------------------
+  - name: procesio_list_workspaces
+    pillar: workspace
+    title: List PROCESIO workspaces
+    description: >
+      List the workspaces this account can reach. A workspace holds its own
+      processes, forms, connectors and credentials.
+    target: {tool: procesio, action: list-workspaces}
+    read_only: true
+    common: [workspace_id, environment]
+    args: []
+
+  - name: procesio_list_environments
+    pillar: workspace
+    title: List PROCESIO environments
+    description: >
+      List the configured environments, so a call can be pointed at the right one.
+    target: {tool: procesio, action: list-environments}
+    read_only: true
+    common: []
+    args: []
+
+  - name: procesio_test_credential
+    pillar: workspace
+    title: Test a PROCESIO credential
+    description: >
+      Check that a stored credential can still reach the system it belongs to.
+      Answers whether a connection is working without running a whole process.
+    target: {tool: procesio, action: credential-test}
+    read_only: true
+    common: [workspace_id, environment]
+    args:
+      - {flag: config, type: string, description: "The credential to test, as a JSON object."}
+
+# Operations kept OUT of the published surface, with the reason. This list is part
+# of the contract: it is where a future "why isn't X here?" gets answered, and it
+# stops an exclusion being quietly reversed by someone who assumes it was an oversight.
+excluded:
+  - target: "procesio/get-process"
+    reason: >
+      Prints its JSON and then does not exit. Over stdio that is an unrecoverable
+      hang rather than an error, and a chat client has no way to recover from it.
+      procesio_list_processes plus procesio_validate_process cover the same need. Revisit only when
+      the action is proven to terminate.
+  - target: "procesio/*-delete"
+    reason: >
+      Irreversible with a data-loss blast class. A first public surface has no
+      deletion in it; the full surface still reaches these behind confirmation.
+      There is a second reason, and it is the stronger one: deleting a resource with a
+      large run history takes longer server-side than the client's read timeout, so the
+      call returns a transport error while the delete goes on to complete. Retrying
+      returns the same error, which reads like a permanent failure and is not one. A
+      caller therefore cannot tell from the response whether the deletion happened - and
+      a tool whose failure signal does not distinguish "nothing happened" from "it is
+      done" has no safe place on a surface a model drives. Confirm by listing the
+      resource, never from the error. (Deletes of credentials and Data Stores return
+      promptly; it is the instance history that costs the time.)
+  - target: "procesio/<generated REST passthroughs>"
+    reason: >
+      Several hundred generated get-/post-/put-/delete- actions mirroring raw API
+      endpoints. They are why the freeform surface exists. Publishing them would
+      make the tool list unreadable and turn the schema into the API reference.
+  - target: "procesio/profile (argument)"
+    reason: >
+      Selects a local credential profile. An installation detail, not a choice a
+      chat user should be asked to make. The default profile is used.

procesio_cli/webplatform/aat_mcp/gate.py

@@ -0,0 +1,68 @@
+"""Reversibility gate for the MCP bridge - code-authoritative, pre-execution.
+
+Reuses the ONE shared definition of "irreversible" (agents/_lib/reversibility) that
+already guards `orchestrator drive` and the `deputy`, so the web platform cannot
+drift into a second policy. The gate decides which execution PATH an action takes:
+
+  reversible  -> runs on `run_tool` / `run_agent`
+  irreversible -> refused there; must go through `run_tool_confirmed` /
+                  `run_agent_confirmed`, which opencode marks `ask` so a HUMAN
+                  approves the click. A model cannot forge that approval, and it
+                  cannot bypass by choosing the plain tool - the plain tool refuses
+                  and names the confirmed path. That is the gate being code, not a
+                  prompt (reversibility.py:1-8).
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[2]
+if str(_REPO) not in sys.path:
+    sys.path.insert(0, str(_REPO))
+
+from agents._lib import reversibility  # noqa: E402
+
+
+def classify(name: str, action: str | None) -> dict:
+    """Classify on the tool/agent NAME + the ACTION verb (send-message,
+    delete-messages, issue-invoice, post-message). Deliberately NOT on arg values -
+    a subject line "please send me..." must not trip the gate; the verb lives in the
+    action name for every AAT side effect. Returns reversibility.classify()'s dict:
+    {reversible, verb, blast_class, reason}."""
+    argv = [action] if action else []
+    return reversibility.classify(name, argv)
+
+
+def deny_irreversible_env() -> bool:
+    """Headless/autonomous fail-safe. When AAT_MCP_DENY_IRREVERSIBLE is set, even the
+    *_confirmed tools refuse irreversible actions - there is no human in the seat to
+    approve. Default (unset) = interactive: opencode's `ask` on the confirmed tools
+    is the human gate."""
+    return os.environ.get("AAT_MCP_DENY_IRREVERSIBLE", "").strip().lower() in (
+        "1", "true", "yes", "on")
+
+
+def decide(name: str, action: str | None, *, level: str = "L1", scopes=None,
+           role: str | None = None, ws_cap: str | None = None) -> dict:
+    """Graded autonomy decision for the MCP layer (spec P0.0-07). Clamps the requested
+    level by the caller's role and any workspace cap, then applies the code-authoritative
+    reversibility gate at the effective level. The `AAT_MCP_DENY_IRREVERSIBLE` fail-safe
+    still hard-denies anything that would need human approval.
+
+    Default (level='L1', no role/cap) reproduces the binary gate exactly: reversible
+    runs, irreversible needs approval - so existing callers are unaffected."""
+    argv = [action] if action else []
+    if role is not None or ws_cap is not None:
+        eff = reversibility.clamp(level, role=role, ws_cap=ws_cap)
+    else:
+        eff = level
+    if eff is None:
+        return {"allow": False, "needs_confirmation": False, "level": None,
+                "reason": "role has no AAT access", "verb": None, "blast_class": None}
+    d = reversibility.decide(name, argv, level=eff, scopes=scopes)
+    if d.get("needs_confirmation") and deny_irreversible_env():
+        return {**d, "allow": False, "needs_confirmation": False,
+                "reason": "AAT_MCP_DENY_IRREVERSIBLE: " + d["reason"]}
+    return d

procesio_cli/webplatform/aat_mcp/http_server.py

@@ -0,0 +1,139 @@
+"""aat-mcp over HTTP (MCP Streamable-HTTP transport) - for containers / k8s, where
+opencode connects as a *remote* MCP client. Reuses server.handle() so stdio and HTTP
+share ONE dispatch + the same reversibility gate.
+
+Endpoint: a single path (default /mcp). Client POSTs a JSON-RPC message (or a batch);
+the server replies with application/json. Notifications (no id) get 202 Accepted. On
+`initialize` the server issues an Mcp-Session-Id header (not enforced - single local
+tenant). GET returns 405 (no server-initiated stream is needed for these tools).
+
+Run:  python webplatform/aat_mcp/http_server.py --host 0.0.0.0 --port 8901 [--token X]
+Auth: if --token or AAT_MCP_HTTP_TOKEN is set, requests must send
+      `Authorization: Bearer <token>` (use for any non-loopback bind).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import server  # noqa: E402  (reuse handle/TOOLS/dispatch)
+
+PATH = "/mcp"
+
+
+def _make_handler(token: str | None):
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, fmt, *args):  # quiet; logs to stderr only if needed
+            sys.stderr.write("[aat-mcp-http] " + (fmt % args) + "\n")
+
+        def _authed(self) -> bool:
+            if not token:
+                return True
+            got = self.headers.get("Authorization", "")
+            return got == f"Bearer {token}"
+
+        def _send(self, code: int, body: bytes | None, ctype: str = "application/json",
+                  extra: dict | None = None):
+            self.send_response(code)
+            if body is not None:
+                self.send_header("Content-Type", ctype)
+                self.send_header("Content-Length", str(len(body)))
+            else:
+                self.send_header("Content-Length", "0")
+            for k, v in (extra or {}).items():
+                self.send_header(k, v)
+            self.end_headers()
+            if body is not None:
+                self.wfile.write(body)
+
+        def do_GET(self):
+            # Health probe convenience + MCP: no server-initiated SSE stream offered.
+            if self.path.rstrip("/") in ("", "/health", "/healthz"):
+                self._send(200, json.dumps({"ok": True, "server": server.SERVER_INFO,
+                                            "tools": [t["name"] for t in server.TOOLS]}
+                                           ).encode())
+                return
+            self._send(405, json.dumps({"error": "GET not supported; POST JSON-RPC to "
+                                        + PATH}).encode())
+
+        def do_POST(self):
+            if self.path.rstrip("/") != PATH.rstrip("/"):
+                self._send(404, json.dumps({"error": f"unknown path; use {PATH}"}).encode())
+                return
+            if not self._authed():
+                self._send(401, json.dumps({"error": "unauthorized"}).encode())
+                return
+            length = int(self.headers.get("Content-Length") or 0)
+            raw = self.rfile.read(length) if length else b""
+            try:
+                msg = json.loads(raw.decode("utf-8")) if raw else None
+            except ValueError:
+                self._send(400, json.dumps(
+                    {"jsonrpc": "2.0", "id": None,
+                     "error": {"code": -32700, "message": "parse error"}}).encode())
+                return
+
+            # Server-established user (multi-user platform). The auth gateway sets
+            # X-AAT-User; it is NEVER taken from the JSON-RPC body / model output. Bound
+            # for this request only, so the tool subprocess runs as that user.
+            uid = self.headers.get("X-AAT-User") or None
+            _utok = server.bridge.set_user(uid)
+            # Same rule for the managed-turn flag: it comes from the CALLER's config (the worker sets
+            # it on every turn it drives), never from the JSON-RPC body, so the model cannot clear it
+            # to unlock a competing orchestration loop.
+            _mtok = server.bridge.set_managed_turn(
+                (self.headers.get("X-AAT-Managed-Turn") or "").strip().lower() in ("1", "true", "yes"))
+            try:
+                batch = msg if isinstance(msg, list) else [msg]
+                responses = []
+                is_initialize = False
+                for m in batch:
+                    if not isinstance(m, dict):
+                        continue
+                    if m.get("method") == "initialize":
+                        is_initialize = True
+                    # Legacy era only: modern Streamable HTTP requires the Mcp-Method / Mcp-Name
+                    # header rules, which this transport does not implement.
+                    resp = server.handle(m, modern=False)
+                    if resp is not None:
+                        responses.append(resp)
+            finally:
+                server.bridge.reset_managed_turn(_mtok)
+                server.bridge.reset_user(_utok)
+
+            if not responses:
+                self._send(202, None)  # only notifications
+                return
+            out = responses if isinstance(msg, list) else responses[0]
+            extra = {"Mcp-Session-Id": uuid.uuid4().hex} if is_initialize else None
+            self._send(200, json.dumps(out, ensure_ascii=False).encode(), extra=extra)
+
+    return Handler
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=8901)
+    ap.add_argument("--token", default=os.environ.get("AAT_MCP_HTTP_TOKEN", ""))
+    a = ap.parse_args()
+    httpd = ThreadingHTTPServer((a.host, a.port), _make_handler(a.token or None))
+    sys.stderr.write(f"[aat-mcp-http] listening on http://{a.host}:{a.port}{PATH} "
+                     f"(auth: {'on' if a.token else 'off'})\n")
+    sys.stderr.flush()
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())