procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/__init__.py

@@ -0,0 +1,18 @@
+"""PROCESIO CLI + Agent - installed entry points.
+
+The repository is path-based: a tool is a folder under ``tools/`` with its own
+``main.py``, and the runner resolves it by path rather than importing it by name
+(``google-calendar`` is a folder name, never a module name). So the wheel ships the
+whole tree under this package and puts this directory on ``sys.path``, which makes
+``import tools`` and ``import registry`` resolve exactly as they do in a clone.
+
+Running from a clone is unchanged and still documented:
+``uv sync`` then ``python scripts/run-tool.py <tool> <action>``.
+"""
+from pathlib import Path
+
+__version__ = "0.1.1"
+
+#: The bundled repository root. In a wheel this directory holds tools/, agents/,
+#: scripts/, skills/ and registry.py; in a clone it is the package beside them.
+ROOT = Path(__file__).resolve().parent

procesio_cli/_cli.py

@@ -0,0 +1,71 @@
+"""Console-script entry points.
+
+Each one runs the corresponding script from the bundled tree, unchanged. Delegating
+with ``runpy`` rather than importing a ``main()`` keeps one code path: the script a
+clone runs and the script an installed package runs are the same file, so they cannot
+drift apart.
+"""
+from __future__ import annotations
+
+import runpy
+import sys
+
+from . import ROOT
+
+
+def _run(script: str, *, where: str = "scripts") -> int:
+    path = ROOT / where / script
+    if not path.is_file():
+        print(f"error: {script} is missing from the installed package", file=sys.stderr)
+        return 2
+    root = str(ROOT)
+    if root not in sys.path:
+        sys.path.insert(0, root)          # so `import tools` / `import registry` resolve
+    sys.argv = [str(path), *sys.argv[1:]]
+    try:
+        runpy.run_path(str(path), run_name="__main__")
+    except SystemExit as exc:             # the scripts exit through sys.exit
+        return int(exc.code or 0)
+    return 0
+
+
+def run_tool() -> int:
+    return _run("run-tool.py")
+
+
+def run_agent() -> int:
+    return _run("run-agent.py")
+
+
+def list_tools() -> int:
+    return _run("list-tools.py")
+
+
+def get_skill() -> int:
+    return _run("get-skill.py")
+
+
+def mcp_server() -> int:
+    """The full stdio MCP server, as a command instead of an absolute path.
+
+    Configuring it used to mean writing /abs/path/to/the/clone into every client's
+    JSON. Installed, the client names a command and the path problem disappears.
+
+    Six generic tools over the whole registry, so any tool you add shows up without
+    integration code. That reach is the point, and it is also why this is not what the
+    plugin launches - see mcp_chat_server.
+    """
+    return _run("server.py", where="webplatform/aat_mcp")
+
+
+def mcp_chat_server() -> int:
+    """The curated stdio MCP server: one named tool per operation.
+
+    What `.mcp.json` launches, and what a general chat client should get. Every tool
+    states what it does and none of them forward a caller-supplied action, which is
+    what makes the surface reviewable - by a person reading a directory listing, and
+    by a model choosing between tools.
+
+    `procesio-mcp` is still there for anyone who wants the whole registry.
+    """
+    return _run("chat_server.py", where="webplatform/aat_mcp")

procesio_cli/agents/_lib/actiondef.py

@@ -0,0 +1,24 @@
+"""ActionDef - dispatchable action unit for agents.
+
+Like the tool-side ActionDef, but instead of a `client` flag it has a `context`
+flag: when True the dispatcher builds the agent's shared context (config + state
+backend) and passes it as the first argument. Pure actions (status, version)
+leave it False and just receive the parsed argparse namespace.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Callable
+
+
+def _no_args(_parser: argparse.ArgumentParser) -> None:
+    return None
+
+
+@dataclass
+class ActionDef:
+    func: Callable
+    add_args: Callable[[argparse.ArgumentParser], None] = _no_args
+    context: bool = False  # True -> dispatch builds the agent context, passes it first
+    description: str = ""

procesio_cli/agents/_lib/errors.py

@@ -0,0 +1,40 @@
+"""Shared error handling for agents.
+
+Mirrors the tool-side contract: every uncaught exception is classified into a
+(code, message, details, exit_code) tuple that becomes the {"error": ...} JSON
+envelope. ToolError from a driven tool is surfaced with its origin preserved.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from agents._lib.toolrunner import ToolError
+
+
+class UsageError(Exception):
+    """Bad CLI usage (unknown action, missing/invalid arg). Exit code 2."""
+
+
+class AgentError(Exception):
+    """Agent-level failure with an explicit error code."""
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None):
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        super().__init__(message)
+
+
+def classify(exc: Exception) -> tuple[str, str, dict[str, Any], int]:
+    if isinstance(exc, UsageError):
+        return "usage_error", str(exc), {}, 2
+    if isinstance(exc, AgentError):
+        return exc.code, exc.message, exc.details, 1
+    if isinstance(exc, ToolError):
+        # A tool the agent drives failed. Keep its code/message and note the tool.
+        details = dict(exc.details)
+        details.setdefault("tool", exc.tool)
+        return f"tool:{exc.code}", f"{exc.tool}: {exc.message}", details, 1
+    if isinstance(exc, KeyError):
+        return "not_found", str(exc), {}, 1
+    return "internal_error", str(exc), {"type": type(exc).__name__}, 1

procesio_cli/agents/_lib/reversibility.py

@@ -0,0 +1,236 @@
+"""Reversibility classification - the shared definition of "irreversible".
+
+The decision policy turns on exactly one axis: reversible, act; irreversible, stop
+and ask a human. This is a MODULE rather than a rule in a prompt because a rule in
+a prompt is something a model can talk itself past. Here it is evaluated BEFORE the
+model is asked anything, so an irreversible action cannot be auto-decided even when
+the prompt is wrong.
+
+Deliberately conservative. A hit means "treat as irreversible" and escalate or
+refuse. A false positive costs one escalation; a false negative costs real-world
+blast radius, and the caller reporting on itself is not a reliable witness. The
+asymmetry is the reason to lean.
+
+KNOW WHAT THIS IS. It matches VERBS, in English, in the action name and argv. An
+action whose name carries no listed verb is reported reversible, so silence here is
+absence of evidence and not a safety guarantee. Treat it as a guard rail that stops
+the obvious mistakes, never as a sandbox: it does not inspect what a call will
+actually do, and it does not read any language but English. Extending the verb list
+is the intended way to close a gap you find.
+
+One definition, one place. The verb list started inside a single agent's driver
+loop; it lives here so that every caller shares it and no two of them can drift
+into different ideas of what "irreversible" means.
+"""
+from __future__ import annotations
+
+import re
+
+# Verbs / action fragments that name an irreversible, real-world side effect.
+# Matched against a tool/agent name, its action verb (argv[0]), and every argv
+# token. Kept as a flat tuple on purpose: greppable, testable, no clever grouping.
+IRREVERSIBLE_VERBS: tuple[str, ...] = (
+    "send", "delete", "remove", "purge", "drop", "pay", "purchase", "buy",
+    "charge", "transfer", "post", "publish", "ban", "kick", "issue-invoice",
+    "wire", "refund", "archive", "revoke", "deactivate", "wipe",
+)
+
+# The four blast-radius classes worth naming: data loss, money out, message sent,
+# someone else's production. Used to explain WHY something escalated, in terms a
+# person recognises rather than an invented taxonomy.
+_CLASS_OF_VERB: dict[str, str] = {
+    "send": "message-sent", "post": "message-sent", "publish": "message-sent",
+    "issue-invoice": "money-out", "pay": "money-out", "purchase": "money-out",
+    "buy": "money-out", "charge": "money-out", "transfer": "money-out",
+    "wire": "money-out", "refund": "money-out",
+    "delete": "data-loss", "remove": "data-loss", "purge": "data-loss",
+    "drop": "data-loss", "wipe": "data-loss", "archive": "data-loss",
+    "ban": "third-party-state", "kick": "third-party-state",
+    "revoke": "third-party-state", "deactivate": "third-party-state",
+}
+
+
+def _probe_hit(probe: str) -> str | None:
+    """Return the irreversible verb matched in one string, or None.
+
+    Word-ish match so `send` hits "send" and "send-message" but not "sender" or
+    "resend-guard". Hyphen/underscore/space are all treated as token separators
+    because tool actions are kebab-case and argv tokens are not.
+    """
+    probe = probe.lower()
+    for verb in IRREVERSIBLE_VERBS:
+        if probe == verb:
+            return verb
+        if re.search(rf"(^|[-_ ]){re.escape(verb)}([-_ ]|$)", probe):
+            return verb
+    return None
+
+
+def match(name: str, argv: list[str] | None = None) -> str | None:
+    """Return the matched irreversible verb for an action, or None.
+
+    Checks the tool/agent name, the action verb (argv[0]), and every argv token.
+    This is the function drive.py's `_looks_irreversible` becomes.
+    """
+    argv = list(argv or [])
+    probes = [str(name)] + [str(tok) for tok in argv]
+    for probe in probes:
+        hit = _probe_hit(probe)
+        if hit:
+            return hit
+    return None
+
+
+def classify(name: str, argv: list[str] | None = None) -> dict:
+    """Classify an action's reversibility.
+
+    Returns:
+        {"reversible": bool, "verb": str|None, "blast_class": str|None,
+         "reason": str}
+
+    `blast_class` is one of money-out, message-sent, data-loss or
+    third-party-state, and None when the action is reversible.
+    """
+    verb = match(name, argv)
+    if verb is None:
+        return {"reversible": True, "verb": None, "blast_class": None,
+                "reason": "no irreversible verb in action name or argv"}
+    blast = _CLASS_OF_VERB.get(verb, "irreversible")
+    return {"reversible": False, "verb": verb, "blast_class": blast,
+            "reason": f"action matches irreversible verb {verb!r} ({blast})"}
+
+
+def classify_text(text: str) -> dict:
+    """Classify a free-text question / proposed action.
+
+    The deputy is asked questions in prose ("should I send the reminder?"), not
+    argv. Same verb list, tokenised over the text. Conservative by construction:
+    any irreversible verb anywhere in the text trips the gate, because the cost of
+    a needless escalation is one WhatsApp line and the cost of a miss is real.
+    """
+    for token in re.split(r"[^\w-]+", str(text).lower()):
+        if not token:
+            continue
+        hit = _probe_hit(token)
+        if hit:
+            blast = _CLASS_OF_VERB.get(hit, "irreversible")
+            return {"reversible": False, "verb": hit, "blast_class": blast,
+                    "reason": f"text names irreversible verb {hit!r} ({blast})"}
+    return {"reversible": True, "verb": None, "blast_class": None,
+            "reason": "no irreversible verb in text"}
+
+
+# ---------------------------------------------------------------------------
+# Autonomy levels (spec P0.0-07). The binary gate above is generalized to four
+# graded levels WITHOUT weakening it: today's behaviour (reversible runs;
+# irreversible needs approval) is exactly L1, the default. Still code-authoritative
+# and evaluated before the model is asked - a model cannot self-escalate.
+# ---------------------------------------------------------------------------
+
+LEVELS: tuple[str, ...] = ("L0", "L1", "L2", "L3")
+_LEVEL_RANK = {lvl: i for i, lvl in enumerate(LEVELS)}
+
+# Verbs that are PURE READS (no side effect). L0 allows ONLY these. Conservative by
+# construction: anything whose primary verb is not clearly a read is refused at L0.
+READ_VERBS: tuple[str, ...] = (
+    "get", "list", "read", "search", "find", "show", "view", "fetch", "status",
+    "describe", "inspect", "check", "count", "lookup", "resolve", "recall", "query",
+    "probe", "catalog", "help", "guidance", "checklist", "summary", "stats",
+)
+
+# role -> the maximum autonomy that role may run or grant (spec P0.0-07 / D14).
+_ROLE_MAX: dict[str, str | None] = {
+    "none": None, "read": "L0", "update": "L1", "write": "L2", "admin": "L3",
+}
+
+
+def _read_hit(probe: str) -> str | None:
+    probe = probe.lower()
+    for verb in READ_VERBS:
+        if probe == verb or re.search(rf"(^|[-_ ]){re.escape(verb)}([-_ ]|$)", probe):
+            return verb
+    return None
+
+
+def is_read_only(name: str, argv: list[str] | None = None) -> bool:
+    """True iff the action has no irreversible verb AND its primary verb (argv[0], else
+    the action name) is a known read verb. Used to gate L0 (read-only)."""
+    argv = list(argv or [])
+    if match(name, argv) is not None:
+        return False
+    primary = str(argv[0]) if argv else str(name)
+    return _read_hit(primary) is not None
+
+
+def _in_scope(name: str, argv: list[str], scopes: set, verb: str | None) -> bool:
+    """L2: is this irreversible action inside the caller-provided allow-list? Matches on
+    the tool/agent name, ``name:action``, the action verb, or the irreversible verb."""
+    if not scopes:
+        return False
+    action = str(argv[0]) if argv else ""
+    cands = {str(name), (f"{name}:{action}" if action else str(name)), action, verb or ""}
+    return bool(cands & set(scopes))
+
+
+def decide(name: str, argv: list[str] | None = None, *, level: str = "L1",
+           scopes=None) -> dict:
+    """Graded autonomy decision, built on ``classify()``. Returns:
+        {allow, needs_confirmation, level, reason, verb, blast_class}
+      - allow=False              -> blocked outright (L0 mutation).
+      - allow, needs_confirmation=False -> runs directly.
+      - allow, needs_confirmation=True  -> runs only via the human-approval path.
+    """
+    argv = list(argv or [])
+    cls = classify(name, argv)
+    lvl = level if level in _LEVEL_RANK else "L1"
+    rank = _LEVEL_RANK[lvl]
+
+    if rank == 0:  # L0 read-only
+        ro = is_read_only(name, argv)
+        return {"allow": ro, "needs_confirmation": False, "level": "L0",
+                "reason": ("read-only action permitted at L0" if ro
+                           else "L0 is read-only; this action may cause a side effect"),
+                "verb": cls["verb"], "blast_class": cls["blast_class"]}
+
+    if cls["reversible"]:  # L1/L2/L3: reversible always runs
+        return {"allow": True, "needs_confirmation": False, "level": lvl,
+                "reason": "reversible action", "verb": None, "blast_class": None}
+
+    if rank == 1:  # L1 ask
+        return {"allow": True, "needs_confirmation": True, "level": "L1",
+                "reason": f"L1: irreversible ({cls['blast_class']}) needs approval",
+                "verb": cls["verb"], "blast_class": cls["blast_class"]}
+
+    if rank == 2:  # L2 bounded
+        if _in_scope(name, argv, set(scopes or []), cls["verb"]):
+            return {"allow": True, "needs_confirmation": False, "level": "L2",
+                    "reason": "L2: irreversible action within authorized scope",
+                    "verb": cls["verb"], "blast_class": cls["blast_class"]}
+        return {"allow": True, "needs_confirmation": True, "level": "L2",
+                "reason": "L2: irreversible action outside scope needs approval",
+                "verb": cls["verb"], "blast_class": cls["blast_class"]}
+
+    # L3 full - irreversible allowed, still classified for the record.
+    return {"allow": True, "needs_confirmation": False, "level": "L3",
+            "reason": "L3: full autonomy (irreversible action logged)",
+            "verb": cls["verb"], "blast_class": cls["blast_class"]}
+
+
+def max_level_for_role(role: str | None) -> str | None:
+    """The maximum autonomy level a role may run/grant. ``None`` = no AAT access."""
+    return _ROLE_MAX.get(str(role or "").strip().lower())
+
+
+def clamp(requested: str, role: str | None = None, ws_cap: str | None = None) -> str | None:
+    """Effective level = min(requested, role-max, workspace-cap). A caller may always
+    choose LOWER than their max. Returns ``None`` iff the role has no AAT access.
+    ``role``/``ws_cap`` unset = not clamped (local single-user), so default is unchanged."""
+    levels = [requested if requested in _LEVEL_RANK else "L1"]
+    if role is not None:
+        role_max = max_level_for_role(role)
+        if role_max is None:
+            return None
+        levels.append(role_max)
+    if ws_cap in _LEVEL_RANK:
+        levels.append(ws_cap)
+    return min(levels, key=lambda lvl: _LEVEL_RANK[lvl])

procesio_cli/agents/_lib/toolrunner.py

@@ -0,0 +1,141 @@
+"""Drive registered tools from an agent.
+
+An agent never imports a tool's internals. It invokes the tool's entrypoint as a
+subprocess and parses the single JSON object the tool prints to stdout — exactly
+the JSON-in / JSON-out contract every tool already honors. This keeps agents
+decoupled: a tool can be rewritten freely as long as its manifest contract holds.
+
+Throughput note: subprocess-per-call adds ~hundreds of ms, which is irrelevant for
+outreach (deliberately throttled, warmup-capped sends) and keeps the boundary clean.
+
+Testability: `invoke` takes an optional `runner` callable so tests can fake tool
+execution without spawning processes or hitting the network.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+_FRAMEWORK_ROOT = Path(__file__).resolve().parents[2]
+if str(_FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(_FRAMEWORK_ROOT))
+
+from registry import get_agent, get_tool  # noqa: E402
+
+# A runner takes the argv list and returns (returncode, stdout, stderr).
+Runner = Callable[[list[str]], "tuple[int, str, str]"]
+
+
+class ToolError(Exception):
+    """A driven tool failed: it returned an {"error": {...}} envelope, produced
+    non-JSON output, or could not be located/spawned."""
+
+    def __init__(self, tool: str, code: str, message: str,
+                 details: dict[str, Any] | None = None):
+        self.tool = tool
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        super().__init__(f"{tool}: {code}: {message}")
+
+
+def _subprocess_runner(timeout: int) -> Runner:
+    def run(cmd: list[str]) -> tuple[int, str, str]:
+        proc = subprocess.run(cmd, capture_output=True, text=True,
+                              encoding="utf-8", timeout=timeout)
+        return proc.returncode, proc.stdout or "", proc.stderr or ""
+    return run
+
+
+def _parse_tool_output(tool: str, stdout: str, stderr: str) -> dict[str, Any]:
+    """Tools emit exactly one JSON object on stdout (logs go to stderr). Parse the
+    last non-empty stdout line defensively, raising ToolError on anything else."""
+    lines = [ln for ln in stdout.splitlines() if ln.strip()]
+    if not lines:
+        raise ToolError(tool, "no_output", "tool produced no stdout",
+                        {"stderr": stderr[-800:]})
+    try:
+        data = json.loads(lines[-1])
+    except ValueError:
+        raise ToolError(tool, "bad_output", "tool stdout was not JSON",
+                        {"stdout": stdout[-800:], "stderr": stderr[-800:]})
+    if isinstance(data, dict) and "error" in data and isinstance(data["error"], dict):
+        err = data["error"]
+        raise ToolError(tool, err.get("code", "tool_error"),
+                        err.get("message", ""), err.get("details") or {})
+    if not isinstance(data, dict):
+        raise ToolError(tool, "bad_output", "tool JSON was not an object",
+                        {"stdout": stdout[-800:]})
+    return data
+
+
+def invoke(tool_name: str, *args: Any, runner: Runner | None = None,
+           timeout: int = 120) -> dict[str, Any]:
+    """Run a registered tool and return its parsed JSON object.
+
+    Example: invoke("apollo", "search-people", "--keywords", "energy", "--per-page", 25)
+    Raises ToolError on tool-not-found, spawn failure, non-JSON output, or an
+    {"error": ...} envelope from the tool.
+    """
+    try:
+        # respect_hidden=False: a scoped surface limits what a session is offered,
+        # it must not break an agent's own plumbing. See registry.get_tool.
+        m = get_tool(tool_name, respect_hidden=False)
+    except KeyError:
+        raise ToolError(tool_name, "tool_not_found",
+                        f"no registered tool named {tool_name!r}")
+    if m.path is None:
+        raise ToolError(tool_name, "no_path", "tool manifest has no path")
+    entry = m.path / m.entrypoint
+    if not entry.exists():
+        raise ToolError(tool_name, "no_entrypoint", f"entrypoint missing: {entry}")
+
+    argv = [sys.executable, str(entry), *[str(a) for a in args]]
+    run = runner or _subprocess_runner(timeout)
+    try:
+        rc, out, err = run(argv)
+    except subprocess.TimeoutExpired:
+        raise ToolError(tool_name, "timeout", f"tool timed out after {timeout}s")
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(tool_name, "spawn_failed", str(exc))
+    # A tool failure still prints a JSON error envelope, so parse before trusting rc.
+    return _parse_tool_output(tool_name, out, err)
+
+
+def invoke_agent(agent_name: str, *args: Any, runner: Runner | None = None,
+                 timeout: int = 300) -> dict[str, Any]:
+    """Run a registered AGENT and return its parsed JSON object.
+
+    An agent honors the same JSON-in / JSON-out contract as a tool (action name
+    as the first positional arg, one JSON object on stdout, {"error": ...} on
+    failure), so this mirrors ``invoke`` but resolves the entrypoint via
+    ``get_agent``. This is what lets the headless ``orchestrator drive`` loop
+    drive OTHER agents (curator, email-classifier, ...) as well as tools.
+
+    Example: invoke_agent("curator", "recall", "--query", "pricing deck")
+    Raises ToolError (with the agent name as ``.tool``) on not-found, spawn
+    failure, non-JSON output, or an {"error": ...} envelope from the agent.
+    """
+    try:
+        m = get_agent(agent_name)
+    except KeyError:
+        raise ToolError(agent_name, "agent_not_found",
+                        f"no registered agent named {agent_name!r}")
+    if m.path is None:
+        raise ToolError(agent_name, "no_path", "agent manifest has no path")
+    entry = m.path / m.entrypoint
+    if not entry.exists():
+        raise ToolError(agent_name, "no_entrypoint", f"entrypoint missing: {entry}")
+
+    argv = [sys.executable, str(entry), *[str(a) for a in args]]
+    run = runner or _subprocess_runner(timeout)
+    try:
+        rc, out, err = run(argv)
+    except subprocess.TimeoutExpired:
+        raise ToolError(agent_name, "timeout", f"agent timed out after {timeout}s")
+    except Exception as exc:  # noqa: BLE001
+        raise ToolError(agent_name, "spawn_failed", str(exc))
+    return _parse_tool_output(agent_name, out, err)

procesio_cli/agents/connector-builder/CONNECTOR-BUILDER-PLAYBOOK.md

@@ -0,0 +1,62 @@
+# Connector Builder — build → test → improve playbook
+
+The operating procedure for producing a working PROCESIO Custom Action with the AI Connector Builder. The agent's `next-step` and `checklist` actions are the executable form of this document.
+
+> **Running it for real?** Read `guidance --topic troubleshooting` alongside this — it has the tool/skill inventory, the live-run realities (sync stages 504 at the proxy but keep running → poll; the clarification-questions shape; the MSYS path gotcha), and the compile failure triage (NU1301 = platform NuGet, not your code, vs NU1102 = a bad version pin you fix in the .csproj). `next-step --build-id` attaches that triage automatically on a failed compile.
+
+## The loop
+
+```
+1 scope     → create-build (API docs + clear requirements)
+2 gather    → gather (GATHER+CLARIFY) → read api_profile + questions
+3 clarify   → answer (every question; keys are the question ids) → PLAN
+4 plan      → revise-plan* then approve-plan → GENERATE (pauses)
+5 generate  → review files; regenerate-file* then approve-generate
+6 validate  → validate-continue / validate-autofix / validate-return-to-generate
+   compile  → (automatic) on failure: retry --from-step 6
+7 deliver   → download-artifact → connector.nupkg
+8 install   → procesio customaction-upload --file connector.nupkg
+9 test      → exercise it in PROCESIO (hand off to the procesio agent)
+10 improve  → feed failures back (see "Where feedback goes")
+11 cleanup  → procesio customaction-delete before re-uploading a new build
+            → recompile, re-upload, repeat 8-11 until green
+```
+
+`*` = repeat as needed before the approve.
+
+## Two ways to drive stages 2-6
+
+- **Manual (default for a first build):** call each stage yourself so you can read and steer every output. Use `next-step --build-id <ID>` after each call.
+- **Automatic:** `start-build --build-id <ID>` runs the entire pipeline as one background task. Poll `get-build`. Use this only once the requirements + clarifications are trusted (it won't pause for review).
+
+## Stage discipline
+
+- **Scope (1).** Requirements are the highest-leverage input. State the operations the connector must expose, the auth scheme, and the data shapes. A vague requirement produces a vague plan and a weak connector. The docs URL is scraped; if the docs are poor, paste the relevant section via `--api-docs-text`.
+- **Clarify (3).** Answer *all* questions — unanswered ones fall back to defaults that may not match intent. The answer keys are the question **ids** returned by `gather` (or `get-build`).
+- **Plan (4).** This is the cheapest place to fix structure (files, classes, methods, NuGet deps, input/output controls). Prefer `revise-plan` here over fixing generated code later. `set-version` is only valid at this stage.
+- **Generate (5).** Review before approving. Fix a single file with `regenerate-file`; use `regenerate` for cross-file/general guidance. Approving moves you into validate→compile→fix→deliver (a background task).
+- **Validate/Compile (6).** Read findings before continuing. On a compile failure, `retry --from-step 6` skips straight to compile→fix→deliver (no regeneration); use `--from-step 4` to regenerate first.
+- **Deliver (7).** The artifact is a real PROCESIO Custom Action `.nupkg`. It is not "done" until it has been **installed and exercised in PROCESIO** — compiling is necessary, not sufficient.
+
+## Where feedback goes (improve, stage 10)
+
+| Symptom seen in PROCESIO | Fix in the builder |
+|---|---|
+| Wrong inputs/outputs, missing operation | `revise-plan` (re-shape) → re-approve |
+| One file's logic wrong | `regenerate-file --filename X --instructions "..."` |
+| Compiles but misbehaves at runtime | `regenerate` with the PROCESIO error text as `--step-instructions` |
+| Validation too weak/strong | edit `validation_rule` knowledge module |
+| **Every connector makes the same mistake** | edit `prompt` / `spec_module` / `example` knowledge, then `reload-config` — this fixes generation for ALL future builds |
+
+The knowledge edits are the deepest loop: they improve the *builder*, not just one connector. Reach for them when you see a systemic pattern (e.g. the model keeps mis-using a PROCESIO SDK decorator) — encode the correction once as a spec module or few-shot example.
+
+## Diagnostics
+
+- `get-build` — current status/step_status + all JSONB state.
+- `logs --success false` — the failing stage's LLM logs (model/cost/tokens, prompt via the admin prompt endpoint).
+- `list-issues --build-id <ID>` / `get-issue` — recorded failure cases with code snapshots (before/after a fix).
+- `build-selftest` — is the compiler service itself healthy? (trivial 2-file C#, no LLM spend.)
+
+## Definition of done
+
+A connector is done when: it compiled, **installed into PROCESIO** (`customaction-list` shows it), and ran correctly inside a real PROCESIO process with expected inputs/outputs — verified per the procesio agent's build-and-test playbook. Anything short of a live PROCESIO run is "compiles", not "works".