procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/agents/connector-builder/CONNECTOR-BUILDER-PROCESIO-INTEROP.md

@@ -0,0 +1,76 @@
+# Connector Builder ⇄ PROCESIO interop
+
+How this agent hands off between the `connector-builder` and `procesio` tools/agents. The whole point of building a connector is to run it in PROCESIO, so this hand-off is the spine of the loop.
+
+## The bridge artifact: the `.nupkg`
+
+The AI Connector Builder produces a compiled **PROCESIO Custom Action package** (`.nupkg`, built with the Custom Actions SDK). That single file is the contract between the two systems:
+
+```
+connector-builder download-artifact --build-id <ID> --out connector.nupkg
+        │  (a real PROCESIO Custom Action package)
+        ▼
+procesio customaction-upload --file connector.nupkg     # POST /api/actions, multipart "package" → {id}
+```
+
+`customaction-upload` returns the new **actionId**. Keep it — you need it to uninstall before re-uploading an improved build.
+
+## Install → verify → cleanup (the procesio side)
+
+```bash
+# 1. Install
+python scripts/run-tool.py procesio customaction-upload --file connector.nupkg     # → {"id": "<actionId>"}
+
+# 2. Confirm it registered
+python scripts/run-tool.py procesio customaction-list                              # the workspace's custom actions
+
+# 3. Test it for real — hand off to the procesio AGENT (owns the test methodology)
+python scripts/run-agent.py procesio verify --process-id <ID>
+#    (build/import a process that uses the action; run it; check inputs/outputs/errors)
+
+# 4. Before re-uploading a NEW build of the same connector, uninstall the old one
+python scripts/run-tool.py procesio customaction-delete --id <actionId>
+```
+
+`customaction-upload` is `CustomActions.Write`; `customaction-delete` is `CustomActions.Delete`. Re-uploading without deleting can leave duplicate/stale actions in the workspace — always `customaction-delete` the prior actionId first.
+
+## Division of labour
+
+| Concern | Owner |
+|---|---|
+| Generate/compile the connector | `connector-builder` tool |
+| Sequence the build pipeline, recommend next step | `connector-builder` **agent** (this one) |
+| Install/uninstall/list the `.nupkg` | `procesio` tool (`customaction-*`) |
+| Test the action inside PROCESIO (processes, forms, webhooks, E2E) | `procesio` **agent** (build-and-test playbook) |
+
+This agent does **not** re-implement PROCESIO testing — it calls the procesio agent's `verify` and reads the procesio agent's playbook (`run-agent.py procesio guidance --topic playbook`). Conversely the procesio agent does not know how to build a connector — it receives a finished `.nupkg`.
+
+## Turning PROCESIO feedback into a better connector
+
+What PROCESIO tells you maps back to a specific connector-builder action:
+
+| PROCESIO observation | Feed back via |
+|---|---|
+| Action's input/output ports are wrong or missing | `connector-builder revise-plan --feedback "..."` → re-approve → re-generate |
+| The action throws / returns wrong data at runtime | `connector-builder regenerate-file --filename <impl>.cs --instructions "<the PROCESIO error>"` |
+| Action metadata/decorators wrong (won't load, bad category) | `regenerate-file` on the decorated class; if recurring, fix the `spec_module` knowledge |
+| The model keeps making the same SDK mistake across connectors | `connector-builder knowledge-update --module-type spec_module|example|prompt ...` then `reload-config` |
+
+Rule of thumb: **per-connector** problems → `revise-plan` / `regenerate*`; **systemic** problems (every connector hits them) → edit the builder's `knowledge`. The procesio-custom-actions skill is the authority on what *correct* SDK usage looks like — cite it when writing knowledge corrections.
+
+## One full pass (concrete)
+
+```bash
+B=<build-id>
+python scripts/run-agent.py connector-builder next-step --build-id $B          # follow until status=completed
+python scripts/run-tool.py  connector-builder download-artifact --build-id $B --out c.nupkg
+ID=$(python scripts/run-tool.py procesio customaction-upload --file c.nupkg | python -c "import sys,json;print(json.load(sys.stdin)['id'])")
+python scripts/run-agent.py procesio verify --process-id <proc-using-the-action>
+# if it failed:
+python scripts/run-tool.py  connector-builder regenerate-file --build-id $B --filename Impl.cs --instructions "<error>"
+python scripts/run-tool.py  connector-builder approve-generate --build-id $B
+python scripts/run-tool.py  connector-builder download-artifact --build-id $B --out c.nupkg
+python scripts/run-tool.py  procesio customaction-delete --id $ID
+python scripts/run-tool.py  procesio customaction-upload --file c.nupkg
+# re-verify … repeat until green
+```

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

@@ -0,0 +1,60 @@
+# Connector Builder — operations & troubleshooting
+
+Everything a session needs to actually RUN the build → test-in-PROCESIO → find-gaps → reiterate loop, including the realities learned from live runs. Read this together with the playbook (the method) and the interop doc (the PROCESIO hand-off). Load all three: `run-agent.py connector-builder guidance --topic all`.
+
+## Tool & skill inventory — what to use for each part of the loop
+
+| Job | Use | How |
+|---|---|---|
+| Build the connector (whole pipeline) | **`connector-builder` tool** | `run-tool.py connector-builder <action>` — create-build, gather, answer, approve-plan/revise-plan, approve-generate/regenerate-file, validate-*, retry, override-stage, download-artifact, logs, get-issue, knowledge-* |
+| Know what to run next | **this agent** | `run-agent.py connector-builder next-step --build-id <ID>` (reads live state, incl. compile-failure triage) |
+| Review generated C# for SDK correctness | **`procesio-custom-actions` skill** | it is the authority on decorators/IAction/credentials/limits — read it before judging generated code or writing knowledge corrections |
+| Install the `.nupkg` into PROCESIO | **`procesio` tool** | `run-tool.py procesio customaction-upload --file <nupkg>` → actionId; `customaction-list`; `customaction-delete --id <actionId>` |
+| Test the action inside PROCESIO | **`procesio` agent** | `run-agent.py procesio verify --process-id <ID>` and its build-and-test playbook (`run-agent.py procesio guidance`) — it owns the PROCESIO-side testing method |
+| Tune the builder itself (systemic) | **`connector-builder` tool** knowledge-* | edit `prompt` / `spec_module` / `example` / `validation_rule` / `clarification`, then `reload-config` |
+
+The agent never re-implements PROCESIO testing — it hands off to the procesio agent. The procesio agent never builds a connector — it receives a finished `.nupkg`.
+
+## Operating reality (from live runs — do not be surprised by these)
+
+- **Synchronous LLM stages 504 at the proxy but keep running server-side.** `gather`, `answer` (PLAN), and `revise-plan` routinely exceed the gateway timeout → without `--wait` the tool returns a clean `api_error` with `status_code: 504`. **This is NOT a failure** — the stage completes server-side. **Preferred:** pass `--wait` to these three (`gather --wait`, `answer --wait`, `revise-plan --wait`) — the tool swallows the 504 and polls `get-build` to the settled state, returning the full build detail (`waited: true`, `settled: true`). Tune with `--wait-timeout` (default 600s) / `--poll-interval` (default 8s). Without `--wait`, poll manually via `get-build` (or `next-step --build-id`) until `status`/`step_status` advance. `approve-plan` / `approve-generate` / `retry` / `start-build` return fast (background tasks) but then run through compile — use **`wait-build --build-id <ID>`** (optionally `--until terminal`) to block until they finish. NOTE: when the *agent* drives a `--wait`/`wait-build` call via toolrunner, pass a subprocess timeout longer than `--wait-timeout` (toolrunner defaults to 120s).
+- **`clarification_questions` is `{"questions": [ {id, question, default, options, context, category, required}, … ]}`** — a dict with a `questions` list, not a bare list. Each question has a sensible PROCESIO-aware `default`. Answering `{id: default}` for all is a solid baseline; override only where the connector needs something specific. Keys in `--answers` are the question **ids** (`q1`, `q2`, …).
+- **Review before every approve.** The plan (step 3) is the cheapest place to fix structure — prefer `revise-plan` over fixing generated code later. At generate (step 5), read the files (`get-build` → `generated_files`, or `list-file-versions`) and `regenerate-file` anything wrong before `approve-generate`.
+- **Windows/Git-Bash gotcha:** the `api --path /admin/...` escape hatch has its leading-slash path rewritten by MSYS (`C:/Program Files/Git/admin/...` → 404). Run those with `MSYS_NO_PATHCONV=1` or from PowerShell. First-class actions are unaffected.
+
+## Failure triage (compile is where it usually bites)
+
+`next-step --build-id <ID>` attaches a `diagnosis` when a build failed at compile. The logic:
+
+- **NU1301 / "failed to retrieve information about '<pkg>'" / can't reach the source index** → **PLATFORM problem, not your code.** The compiler can't pull the PROCESIO SDK (`Ringhel.Procesio.Action.Core`) from GitHub Packages. Regenerating is useless. Check `get-config --which compilation` (nuget_sources) and `POST /admin/platform-settings/test-nuget` — but note test-nuget only validates the ORG index, and `build-selftest` passes without the SDK, so neither proves the SDK package is restorable. Fix is server-side (grant the GitHub Packages PAT read access to the SDK package, or mirror it to a reachable feed), then `retry --from-step 6`. *No code change needed — the generated code stays parked at step 6 and completes once restore works.* (This is exactly what happened on the first real build.)
+- **(NU1301 above was resolved by 2026-10: SDK restore from GitHub Packages works; Action-Core 2.1.0 restores fine.)**
+- **NU1605 "detected package downgrade: Newtonsoft.Json" → CODE problem.** Action-Core 2.1.0 depends on Newtonsoft.Json 13.0.4; a `.csproj` pinning 13.0.3 cannot restore. Pin 13.0.4.
+- **NU1102 / "unable to find package … version" → CODE problem.** The `.csproj` pinned a non-existent version. Read it (`get-file-version --filename *.csproj`), fix the version (`update-file`), then `retry --from-step 6`.
+- **Real C# errors → CODE problem.** Let the FIX loop try (`retry --from-step 6`); if it can't, `override-stage` back to generate and `regenerate-file` the offending file with the compiler error as instructions.
+
+Distinguish **transient vs deterministic**: retry once; if the same restore error repeats, it's deterministic → platform, escalate rather than loop. Every failure also writes a `stage_logs` row (`logs --stage compile --success false`) and often an issue case (`list-issues --build-id` / `get-issue`) with a before/after code snapshot.
+
+## Turning PROCESIO feedback into a better connector (reiterate)
+
+After `customaction-upload` + a `procesio verify` run, map what you see back to an action:
+
+| PROCESIO observation | Feed back via |
+|---|---|
+| Wrong/missing input or output ports | `revise-plan` → re-approve → regenerate |
+| Action throws / returns wrong data at runtime | `regenerate-file --filename <impl>.cs --instructions "<the PROCESIO error>"` |
+| Won't load / bad metadata / wrong category | `regenerate-file` on the decorated class; if recurring, fix the `spec_module` knowledge |
+| Upload rejected 261 "Expects value type does not match the property type" | `regenerate-file` the action class: a nullable `int?` cannot carry `Expects`; use non-nullable `int` (or a string) |
+| Action runs but its HTTP call times out, while the API answers from your machine | Probe the host from PROCESIO (`procesio credential-create --dry-run` with a no-auth REST API credential); an unreachable host is an egress problem, not code |
+| Generation looks like it ignores a knowledge edit | `knowledge-list` for a `"source": "database"` override of that module; rewrite it with `knowledge-update --content-file` (never delete it: delete tombstones the base too) |
+| Every connector repeats the same SDK mistake | `knowledge-update --module-type spec_module|example|prompt …` then `reload-config` (improves ALL future builds) |
+
+Per-connector problems → `revise-plan` / `regenerate*`. Systemic problems → edit `knowledge`. Cite the `procesio-custom-actions` skill for what *correct* SDK usage is when writing a knowledge correction. Before re-uploading a fixed build, `procesio customaction-delete --id <old actionId>` so you don't leave stale duplicates.
+
+## Definition of done — "as expected"
+
+A connector is done ONLY when all of these hold:
+1. It **compiled** (`status: completed`, a `.nupkg` downloads).
+2. It **installed** into PROCESIO (`customaction-list` shows it, `isCustom: true`).
+3. It **ran correctly inside a real PROCESIO process** — expected inputs produce expected outputs, and the designed error path behaves (e.g. an API that returns HTTP 200 with `ok:false` sets the error output and does not throw), verified per the procesio agent's build-and-test playbook.
+
+Compiling and installing are necessary, not sufficient. Keep iterating (test → diagnose → improve → recompile → re-upload) until step 3 passes. If step 3 needs a live credential (e.g. a Slack bot token) and none is available, the runtime test is the one open item — say so explicitly rather than declaring done.

procesio_cli/agents/connector-builder/README.md

@@ -0,0 +1,51 @@
+# connector-builder agent
+
+Orchestrates the **AI Connector Builder** ([connector-builder.procesio.app](https://connector-builder.procesio.app)) and **PROCESIO** to run one loop end to end:
+
+```
+API docs → [connector-builder] build a Custom Action → download .nupkg
+        → [procesio] install + test it live → capture failures
+        → [connector-builder] improve (revise plan / regenerate / tune knowledge)
+        → recompile → re-upload → repeat until it passes
+```
+
+It is the **executable doctrine** for that loop. Tool mechanics live in `tools/connector-builder/` and `tools/procesio/`; this agent decides *what to run next* and *how the two tools hand off*.
+
+## Tool-vs-agent boundary
+
+- **`connector-builder` tool** — the REST client. One subprocess call per API action (create-build, gather, answer, approve-*, download-artifact, knowledge-*, …). No methodology, just the wire.
+- **`procesio` tool** — installs/uninstalls the produced `.nupkg` (`customaction-upload` / `customaction-delete` / `customaction-list`) and runs processes.
+- **this agent** — sequences those calls. It never imports a tool's internals; it drives them through the registry via `agents/_lib/toolrunner`.
+- **`procesio` agent** — owns the PROCESIO-side *testing* methodology (the build-and-test playbook: validate/run/forms/webhooks/E2E). This agent hands off to it at the "test" step.
+
+## Actions
+
+```bash
+# Readiness (this agent + connector-builder + procesio tools)
+python scripts/run-agent.py connector-builder status
+
+# The whole loop as a checklist (optionally for a goal)
+python scripts/run-agent.py connector-builder checklist --goal "Stripe refunds connector"
+
+# What do I run next? — live, from the build's real state
+python scripts/run-agent.py connector-builder next-step --build-id <ID>
+# …or classify a known state pair without a live call
+python scripts/run-agent.py connector-builder next-step --status generating --step-status waiting_user
+
+# Load the methodology
+python scripts/run-agent.py connector-builder guidance --topic playbook
+python scripts/run-agent.py connector-builder guidance --topic interop
+```
+
+`next-step` turns the 8-stage pipeline state machine into a single "what now?" answer, including the PROCESIO hand-off once the connector compiles. `checklist` is the same loop as an ordered, executable list.
+
+## Knowledge base (served by `guidance`)
+
+- **CONNECTOR-BUILDER-PLAYBOOK.md** — the operating procedure for the build→test→improve loop.
+- **CONNECTOR-BUILDER-PROCESIO-INTEROP.md** — the precise hand-off between the connector-builder and procesio tools/agent (the `.nupkg` bridge, upload/test/cleanup, where each improvement type goes).
+- **README.md** — this file (overview + boundary).
+
+## Design notes
+
+- The agent dir name is hyphenated, so its modules are imported by BARE name with the agent root on sys.path (like the hyphenated tools); shared agent libs come from `agents._lib`.
+- Stateless: no state backend, no own secret. Readiness comes from the tools it drives.

procesio_cli/agents/connector-builder/agent.yaml

@@ -0,0 +1,61 @@
+name: connector-builder
+description: >-
+  Connector-building orchestration agent for PROCESIO. Drives the
+  `connector-builder` tool (the AI Connector Builder REST client at
+  connector-builder.procesio.app) and the `procesio` tool to run the full loop:
+  generate a Custom Action connector from API docs → download the compiled .nupkg
+  → upload it to PROCESIO → test it live → feed failures back to improve the
+  connector (and, for systemic issues, the builder's own knowledge base). It is
+  the executable side of the build→test→improve playbook in this folder and the
+  bridge to the procesio agent's build-and-test playbook. Tool mechanics stay in
+  tools/connector-builder/; methodology lives here.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+# Tools this agent DRIVES (registry-resolved, never hardcoded at call sites).
+# Readiness is derived from this list: connector-builder for the build pipeline,
+# procesio to install + test the produced .nupkg in a real workspace.
+tools:
+  - connector-builder
+  - procesio
+
+routing:
+  triggers:
+    - build a PROCESIO custom action / connector from API docs and test it
+    - drive the AI Connector Builder end to end (gather → plan → generate → compile)
+    - what's the next step for this connector build
+    - upload a generated connector to PROCESIO and improve it from the feedback
+    - how do I run the connector build → test → improve loop
+  primary_action: next-step
+  example: >-
+    connector-builder next-step --build-id <ID>   (checklist: connector-builder
+    checklist; guidance: connector-builder guidance --topic playbook; status:
+    connector-builder status)
+
+actions:
+  - name: status
+    description: Report agent + driven-tool readiness (connector-builder, procesio).
+  - name: guidance
+    description: >-
+      Serve the build→test→improve playbook + PROCESIO interop doctrine from one
+      registry-discoverable place.
+    args:
+      - {name: topic, type: string, default: all, description: "playbook | interop | troubleshooting | boundary | all"}
+  - name: next-step
+    description: >-
+      Recommend the next pipeline action for a build's state. Reads status live
+      with --build-id (drives connector-builder get-build), or classify a given
+      --status / --step-status pair. Includes the hand-off to PROCESIO at deliver.
+    args:
+      - {name: build-id, type: string, description: "Read live status from the connector-builder tool"}
+      - {name: status, type: string, description: "Build overall status (if not using --build-id)"}
+      - {name: step-status, type: string, description: "running | waiting_user (refines the recommendation)"}
+  - name: checklist
+    description: Emit the end-to-end build→upload→test→improve checklist as structured steps.
+    args:
+      - {name: goal, type: string, description: "Optional one-line connector goal to stamp in"}
+
+# No own secret: readiness comes from the tools it drives. The connector-builder
+# API credentials and the PROCESIO credentials belong to those tools.
+secrets: []

procesio_cli/agents/connector-builder/context.py

@@ -0,0 +1,19 @@
+"""Runtime context for the connector-builder agent.
+
+Stateless: the only thing context-actions need is a tool invoker so they can
+drive the `connector-builder` and `procesio` tools (tests replace it with a
+fake). The agent has no secret of its own — readiness comes from the tools it
+drives.
+"""
+from __future__ import annotations
+
+from agents._lib import toolrunner
+
+
+class ConnectorBuilderContext:
+    def __init__(self, invoke=None):
+        self.invoke = invoke or toolrunner.invoke
+
+    @classmethod
+    def create(cls, invoke=None) -> "ConnectorBuilderContext":
+        return cls(invoke=invoke)

procesio_cli/agents/connector-builder/handlers/__init__.py

@@ -0,0 +1 @@
+"""connector-builder agent action handlers (imported by BARE name from main.py)."""

procesio_cli/agents/connector-builder/handlers/checklist.py

@@ -0,0 +1,71 @@
+"""checklist action — emit the end-to-end build → upload → test → improve
+checklist as structured steps, so a session can execute the loop deterministically.
+
+Pure (no live calls); optionally stamps a --goal into the first step's note.
+"""
+from __future__ import annotations
+
+import argparse
+
+from agents._lib.actiondef import ActionDef
+
+_STEPS = [
+    {"phase": "scope", "tool": "connector-builder", "action": "create-build",
+     "do": "Create the build from the API docs URL(s) or pasted text + clear user-requirements.",
+     "command": "create-build --api-url <docs> --user-requirements '...'"},
+    {"phase": "gather", "tool": "connector-builder", "action": "gather",
+     "do": "Run GATHER+CLARIFY; read the api_profile and clarification_questions.",
+     "command": "gather --build-id <ID>"},
+    {"phase": "clarify", "tool": "connector-builder", "action": "answer",
+     "do": "Answer every clarification question (keys = question ids). Triggers PLAN.",
+     "command": "answer --build-id <ID> --answers '{...}'"},
+    {"phase": "plan", "tool": "connector-builder", "action": "approve-plan / revise-plan",
+     "do": "Review the implementation plan. revise-plan until right, then approve-plan.",
+     "command": "revise-plan --feedback '...'  |  approve-plan --build-id <ID>"},
+    {"phase": "generate", "tool": "connector-builder", "action": "approve-generate / regenerate-file",
+     "do": "Review generated files; regenerate any wrong file; then approve-generate.",
+     "command": "regenerate-file --filename X.cs --instructions '...'  |  approve-generate"},
+    {"phase": "validate+compile", "tool": "connector-builder", "action": "validate-* / retry",
+     "do": "Clear validation findings; let it compile. On compile failure, retry --from-step 6.",
+     "command": "validate-continue  |  retry --from-step 6"},
+    {"phase": "deliver", "tool": "connector-builder", "action": "download-artifact",
+     "do": "Download the compiled .nupkg.",
+     "command": "download-artifact --build-id <ID> --out connector.nupkg"},
+    {"phase": "install", "tool": "procesio", "action": "customaction-upload",
+     "do": "Install the connector into the PROCESIO workspace.",
+     "command": "procesio customaction-upload --file connector.nupkg"},
+    {"phase": "test", "tool": "procesio (agent)", "action": "verify",
+     "do": "Exercise the action in a real process (inputs/outputs, errors) per the procesio build-and-test playbook.",
+     "command": "run-agent.py procesio verify --process-id <ID>"},
+    {"phase": "improve", "tool": "connector-builder", "action": "revise-plan / regenerate-file / knowledge-update",
+     "do": "Feed PROCESIO failures back: fix the plan/code for this connector; for systemic generation issues edit the builder's knowledge (prompt/spec_module/example) then reload-config. Re-compile and re-upload.",
+     "command": "regenerate-file ...  |  knowledge-update --module-type spec_module ...; reload-config"},
+    {"phase": "cleanup", "tool": "procesio", "action": "customaction-delete",
+     "do": "Before re-uploading a new build of the same connector, uninstall the old one.",
+     "command": "procesio customaction-delete --id <actionId>"},
+]
+
+
+def _checklist(args) -> dict:
+    steps = [dict(s, n=i + 1) for i, s in enumerate(_STEPS)]
+    out = {
+        "title": "Connector build → PROCESIO test → improve loop",
+        "loop": "Steps 8-11 repeat until the action passes its PROCESIO tests.",
+        "steps": steps,
+    }
+    if args.goal:
+        out["goal"] = args.goal
+        steps[0]["note"] = f"Goal: {args.goal}"
+    return out
+
+
+def _checklist_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--goal", help="Optional one-line connector goal to stamp in")
+
+
+ACTIONS = {
+    "checklist": ActionDef(
+        func=_checklist, add_args=_checklist_args,
+        description="Emit the end-to-end build→upload→test→improve checklist.",
+    ),
+}

procesio_cli/agents/connector-builder/handlers/guidance.py

@@ -0,0 +1,37 @@
+"""guidance action — serve the agent's operating doctrine from one place.
+
+Loads the playbook / interop / boundary markdown so a session reads the
+methodology instead of re-deriving it. Pure file read; no live calls.
+"""
+from __future__ import annotations
+
+import argparse
+
+from agents._lib.actiondef import ActionDef
+from agents._lib.errors import AgentError
+
+import knowledge
+
+
+def _guidance(args) -> dict:
+    topic = (args.topic or "all").strip().lower()
+    if topic == "all":
+        return {"topics": knowledge.topics(), "documents": knowledge.load_all()}
+    try:
+        return knowledge.load(topic)
+    except KeyError as e:
+        raise AgentError("unknown_topic", str(e),
+                         {"known": knowledge.topics()}) from e
+
+
+def _guidance_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--topic", default="all",
+                   help="playbook | interop | boundary | all")
+
+
+ACTIONS = {
+    "guidance": ActionDef(
+        func=_guidance, add_args=_guidance_args,
+        description="Serve the build→test→improve playbook + PROCESIO interop doctrine.",
+    ),
+}

procesio_cli/agents/connector-builder/handlers/nextstep.py

@@ -0,0 +1,221 @@
+"""next-step action — the executable pipeline doctrine.
+
+Given a build's (status, step_status) — passed in, or read LIVE from the
+`connector-builder` tool via --build-id — recommend the next tool call(s). This
+turns the 8-stage state machine (documentation/04-PIPELINE-ENGINE.md) into a
+single "what do I run now?" answer, including the hand-off to PROCESIO once the
+connector is built.
+
+Pure heuristic over the state pair; the only live call is the optional get-build
+lookup. No secrets of its own.
+"""
+from __future__ import annotations
+
+import argparse
+
+from agents._lib.actiondef import ActionDef
+from agents._lib.errors import AgentError
+
+_T = "connector-builder"  # the tool name, for the suggested commands
+
+
+def _cmd(action: str, extra: str = "") -> str:
+    base = f"python scripts/run-tool.py {_T} {action} --build-id <ID>"
+    return f"{base} {extra}".strip()
+
+
+# Recommendations keyed by overall status. Where step_status matters
+# (waiting_user vs running) the value is a dict of step_status -> plan.
+_RUNNING = {
+    "phase": "running",
+    "poll": True,
+    "recommended": [{"action": "get-build", "why": "stage is executing; poll until it pauses or finishes",
+                     "command": _cmd("get-build")}],
+}
+
+
+def _compile_failure_diagnosis(error_message: str | None) -> dict | None:
+    """Triage a COMPILE failure from its error text (the live-run learning).
+
+    NuGet RESTORE failures (NU1301 / can't reach the source/package index) are a
+    PLATFORM config problem — the compiler can't pull the PROCESIO SDK from GitHub
+    Packages — NOT a code problem, so regenerating is useless. A MISSING VERSION
+    (NU1102) IS a code problem: the .csproj pinned a version that doesn't exist,
+    fixable with update-file. Real C# errors are code problems the FIX loop or a
+    regenerate handles.
+    """
+    e = (error_message or "").lower()
+    if not e:
+        return None
+    if "nu1301" in e or ("restore" in e and "nuget" in e) or "retrieve information about" in e:
+        return {
+            "kind": "platform_nuget_restore",
+            "not_your_code": True,
+            "why": ("NU1301 = the compiler could not reach the package source/index "
+                    "(the PROCESIO SDK on GitHub Packages). This is a server-side NuGet "
+                    "config issue, NOT the generated code — regenerating will not help."),
+            "fix": [
+                "python scripts/run-tool.py connector-builder get-config --which compilation   # inspect nuget_sources",
+                "MSYS_NO_PATHCONV=1 python scripts/run-tool.py connector-builder api --method POST --path /admin/platform-settings/test-nuget   # validate PAT",
+                "Fix platform-side: grant the GitHub Packages PAT read access to Ringhel.Procesio.Action.Core (or mirror the SDK to a reachable feed).",
+                _cmd("retry", "--from-step 6") + "   # once the source is reachable",
+            ],
+        }
+    if "nu1102" in e or "unable to find package" in e:
+        return {
+            "kind": "bad_package_version",
+            "not_your_code": False,
+            "why": "NU1102 = the .csproj pinned a package version that does not exist.",
+            "fix": [
+                _cmd("get-file-version", "--filename <name>.csproj --version 1") + "   # read the pin",
+                _cmd("update-file", "--filename <name>.csproj --content-file fixed.csproj") + "   # fix the version",
+                _cmd("retry", "--from-step 6"),
+            ],
+        }
+    return {
+        "kind": "code_error",
+        "not_your_code": False,
+        "why": "Looks like a C#/compile error in the generated code.",
+        "fix": [
+            _cmd("logs", "--stage compile --success false") + "   # read the exact errors",
+            _cmd("retry", "--from-step 6") + "   # let the FIX loop attempt a correction",
+            "OR override-stage back to generate and regenerate-file the offending file.",
+        ],
+    }
+
+
+def _recommend(status: str, step_status: str | None,
+               error_message: str | None = None, last_failed_step=None) -> dict:
+    s = (status or "").strip().lower()
+    ss = (step_status or "").strip().lower() or None
+
+    if s in ("", "pending"):
+        return {"phase": "pending", "poll": False, "recommended": [
+            {"action": "start-build", "why": "run the entire pipeline as one background task",
+             "command": _cmd("start-build")},
+            {"action": "gather", "why": "OR drive it manually, one stage at a time (synchronous GATHER+CLARIFY)",
+             "command": _cmd("gather")},
+        ]}
+
+    if s in ("gathering", "compiling", "fixing", "delivering"):
+        return dict(_RUNNING, phase=s)
+
+    if s == "clarifying":
+        return {"phase": "clarify", "poll": False, "recommended": [
+            {"action": "answer", "why": "submit answers to the clarification questions (keys are the question ids); triggers PLAN",
+             "command": _cmd("answer", "--answers '{\"q1\":\"...\"}'")},
+        ], "also": [{"action": "get-build", "why": "re-read clarification_questions if you don't have them",
+                     "command": _cmd("get-build")}]}
+
+    if s == "planning":
+        if ss == "running":
+            return dict(_RUNNING, phase="planning")
+        return {"phase": "plan-review", "poll": False, "recommended": [
+            {"action": "approve-plan", "why": "plan looks right → generate code (pauses after)",
+             "command": _cmd("approve-plan")},
+            {"action": "revise-plan", "why": "OR change the plan first",
+             "command": _cmd("revise-plan", "--feedback '...'")},
+        ], "also": [{"action": "set-version", "why": "optionally set Major.Minor.Patch (only valid here)",
+                     "command": _cmd("set-version", "--major 1 --minor 0 --patch 0")}]}
+
+    if s == "generating":
+        if ss == "running":
+            return dict(_RUNNING, phase="generating")
+        return {"phase": "generate-review", "poll": False, "recommended": [
+            {"action": "approve-generate", "why": "files look right → VALIDATE→COMPILE→FIX→DELIVER",
+             "command": _cmd("approve-generate")},
+            {"action": "regenerate-file", "why": "OR fix one file",
+             "command": _cmd("regenerate-file", "--filename X.cs --instructions '...'")},
+            {"action": "regenerate", "why": "OR regenerate with general/per-file instructions",
+             "command": _cmd("regenerate", "--step-instructions '...'")},
+        ], "also": [{"action": "list-file-versions", "why": "inspect what was generated first",
+                     "command": _cmd("list-file-versions")}]}
+
+    if s == "validating":
+        if ss == "running":
+            return dict(_RUNNING, phase="validating")
+        return {"phase": "validate-review", "poll": False, "recommended": [
+            {"action": "validate-continue", "why": "accept findings and proceed to COMPILE",
+             "command": _cmd("validate-continue")},
+            {"action": "validate-autofix", "why": "OR let the LLM auto-fix the findings",
+             "command": _cmd("validate-autofix")},
+            {"action": "validate-return-to-generate", "why": "OR go back to GENERATE",
+             "command": _cmd("validate-return-to-generate")},
+        ]}
+
+    if s in ("completed", "delivered", "succeeded"):
+        return {"phase": "deliver", "poll": False, "recommended": [
+            {"action": "download-artifact", "why": "download the compiled .nupkg",
+             "command": _cmd("download-artifact", "--out connector.nupkg")},
+        ], "handoff": [
+            {"tool": "procesio", "action": "customaction-upload",
+             "why": "install the connector in PROCESIO to test it live",
+             "command": "python scripts/run-tool.py procesio customaction-upload --file connector.nupkg"},
+            {"tool": "procesio (agent)", "action": "verify",
+             "why": "exercise the action in a real process per the build-and-test playbook",
+             "command": "python scripts/run-agent.py procesio verify --process-id <ID>"},
+        ]}
+
+    if s == "failed":
+        out = {"phase": "failed", "poll": False, "recommended": [
+            {"action": "logs", "why": "read the failing stage logs first (filter --success false)",
+             "command": _cmd("logs", "--success false")},
+            {"action": "retry", "why": "retry from the last failed step (or --from-step N: ≥6 = compile→deliver)",
+             "command": _cmd("retry")},
+            {"action": "reset", "why": "OR wipe pipeline state back to pending (only from failed/clarifying/planning)",
+             "command": _cmd("reset")},
+        ], "also": [{"action": "get-issue", "why": "if an issue case was recorded, read its snapshot",
+                     "command": f"python scripts/run-tool.py {_T} list-issues --build-id <ID>"}]}
+        # Step 6 = compile: triage restore-vs-code so you don't regenerate a
+        # platform NuGet problem (the live-run learning).
+        if last_failed_step in (6, "6") or "compil" in (error_message or "").lower() \
+                or "nuget" in (error_message or "").lower() or "nu13" in (error_message or "").lower():
+            diag = _compile_failure_diagnosis(error_message)
+            if diag:
+                out["diagnosis"] = diag
+        return out
+
+    raise AgentError("unknown_status", f"unrecognised build status: {status!r}",
+                     {"known_statuses": ["pending", "gathering", "clarifying", "planning",
+                                         "generating", "validating", "compiling", "fixing",
+                                         "completed", "failed"]})
+
+
+def _next_step(ctx, args) -> dict:
+    status = args.status
+    step_status = args.step_status
+    build = None
+    error_message = None
+    last_failed_step = None
+    if args.build_id:
+        build = ctx.invoke(_T, "get-build", "--build-id", args.build_id)
+        status = build.get("status", status)
+        step_status = build.get("step_status", step_status)
+        error_message = build.get("error_message")
+        last_failed_step = build.get("last_failed_step")
+    if not status:
+        raise AgentError("missing_input",
+                         "provide --status (and optional --step-status) or --build-id",
+                         {})
+    plan = _recommend(status, step_status, error_message, last_failed_step)
+    plan["build_status"] = status
+    plan["step_status"] = step_status
+    if args.build_id:
+        plan["build_id"] = args.build_id
+    return plan
+
+
+def _next_step_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--build-id", dest="build_id",
+                   help="Read live status from the connector-builder tool")
+    p.add_argument("--status", help="Build overall status (if not using --build-id)")
+    p.add_argument("--step-status", dest="step_status",
+                   help="running | waiting_user (refines the recommendation)")
+
+
+ACTIONS = {
+    "next-step": ActionDef(
+        func=_next_step, add_args=_next_step_args, context=True,
+        description="Recommend the next pipeline action for a build's state (live via --build-id).",
+    ),
+}

procesio_cli/agents/connector-builder/handlers/status.py

@@ -0,0 +1,35 @@
+"""status action — report the connector-builder agent's readiness and that of the
+tools it drives (`connector-builder`, `procesio`). Pure registry introspection:
+no network, no secrets. A tool not yet registered/ready surfaces as unready, never
+an error.
+"""
+from __future__ import annotations
+
+from agents._lib.actiondef import ActionDef
+
+
+def _status(_args) -> dict:
+    from registry import list_agents
+
+    me = next((a for a in list_agents() if a.get("name") == "connector-builder"), None)
+    if me is None:
+        return {"agent": "connector-builder", "found": False,
+                "note": "agent.yaml not discovered by the registry"}
+    tools = me.get("tool_status", {})
+    return {
+        "agent": "connector-builder",
+        "found": True,
+        "version": me.get("version"),
+        "ready": me.get("ready", False),
+        "missing_secrets": me.get("missing_secrets", []),
+        "tools_ready": sorted(n for n, s in tools.items() if s.get("ready")),
+        "tools_unready": {n: s for n, s in tools.items() if not s.get("ready")},
+    }
+
+
+ACTIONS = {
+    "status": ActionDef(
+        func=_status,
+        description="Report agent + driven-tool readiness (connector-builder, procesio).",
+    ),
+}