procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/_lib/websession.py

@@ -0,0 +1,194 @@
+"""Web-session lifecycle abstraction: hydrate / dehydrate / lease (spec P0.0-09).
+
+The PROCESIO web-tool service hosts per-(workspace, user) browser profiles: hydrate a
+profile from object storage -> run -> dehydrate it back, with a per-session lease so one
+profile is driven by one browser at a time (the single-owner ``SingletonLock`` reality
+of a persistent Chrome profile - memory ``web-profile-no-parallel``; the local
+serialize-web-profile broker). See
+``todo/on-hold/procesio-aat-module/09-web-tool-service.md``.
+
+This module factors that lifecycle into a reusable abstraction with a **local
+filesystem** implementation, so the platform swaps the storage + lease backends
+(object storage + a distributed lease) without changing any caller. P0.0 delivers the
+shape + the local impl + the object-store swap point - NOT a hosted browser fleet.
+
+Metadata mirrors the CSK session pointer: {name, site, kind, created, rotated, health}.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[2]
+if str(_REPO) not in sys.path:
+    sys.path.insert(0, str(_REPO))
+
+from tools._lib import userdata  # noqa: E402
+
+
+class LeaseTimeout(RuntimeError):
+    """Raised when a per-session lease cannot be acquired within the timeout - the
+    session is in use by another browser (serialized single-owner access)."""
+
+
+class WebSessionStore(ABC):
+    """Persistence + lease contract for web-login profiles. Backends are dumb: the
+    caller decides when to hydrate/dehydrate; the store moves bytes and guards leases."""
+
+    @abstractmethod
+    def hydrate(self, ws: str | None, user: str | None, name: str) -> Path:
+        """Materialize the session's profile locally and return its directory."""
+
+    @abstractmethod
+    def dehydrate(self, ws: str | None, user: str | None, name: str, profile_dir: Path) -> None:
+        """Persist profile changes back to durable storage."""
+
+    @abstractmethod
+    def list_sessions(self, ws: str | None, user: str | None) -> list[dict]:
+        ...
+
+    @abstractmethod
+    def pointer(self, ws: str | None, user: str | None, name: str) -> dict | None:
+        ...
+
+    @abstractmethod
+    def _lock_path(self, ws: str | None, user: str | None, name: str) -> Path:
+        ...
+
+    @contextmanager
+    def lease(self, ws: str | None, user: str | None, name: str, *,
+              timeout: float = 30.0, poll: float = 0.1):
+        """Acquire exclusive use of one session, hydrate it, yield the profile dir, then
+        dehydrate + release. Serializes same-session access (a second acquirer waits up
+        to ``timeout`` then raises ``LeaseTimeout``); different sessions run in parallel.
+        The platform swaps this for a distributed lease with identical semantics."""
+        lock = self._lock_path(ws, user, name)
+        lock.parent.mkdir(parents=True, exist_ok=True)
+        fd = _acquire_lock(lock, timeout=timeout, poll=poll)
+        try:
+            profile_dir = self.hydrate(ws, user, name)
+            try:
+                yield profile_dir
+            finally:
+                self.dehydrate(ws, user, name, profile_dir)
+        finally:
+            _release_lock(fd, lock)
+
+
+class LocalWebSessionStore(WebSessionStore):
+    """Filesystem implementation. Profiles live under ``userdata.sessions_dir()`` which
+    is already per-(workspace, user) once ``AAT_WORKSPACE_ID`` / ``AAT_USER_ID`` are set
+    (item P0.0-01), so tenant isolation is automatic. Hydrate/dehydrate are in-place
+    (the durable copy IS the local dir); the object-store impl overrides them to move
+    bytes to/from S3/MinIO."""
+
+    def _root(self, ws: str | None, user: str | None) -> Path:
+        # sessions_dir() derives from userdata.base(), which already folds in (ws,user).
+        return userdata.sessions_dir()
+
+    def _session_dir(self, ws, user, name: str) -> Path:
+        return self._root(ws, user) / userdata._safe_component(name)
+
+    def _index_path(self, ws, user) -> Path:
+        return self._root(ws, user) / "sessions_index.json"
+
+    def _lock_path(self, ws, user, name: str) -> Path:
+        return self._session_dir(ws, user, name).with_suffix(".lock")
+
+    def hydrate(self, ws, user, name: str) -> Path:
+        d = self._session_dir(ws, user, name)
+        (d / "profile").mkdir(parents=True, exist_ok=True)
+        return d / "profile"
+
+    def dehydrate(self, ws, user, name: str, profile_dir: Path) -> None:
+        # Local: the profile dir IS durable; just touch the pointer's rotated time.
+        self._touch_pointer(ws, user, name)
+
+    def _load_index(self, ws, user) -> dict:
+        p = self._index_path(ws, user)
+        if p.exists():
+            try:
+                return json.loads(p.read_text(encoding="utf-8"))
+            except (ValueError, OSError):
+                return {}
+        return {}
+
+    def _save_index(self, ws, user, idx: dict) -> None:
+        p = self._index_path(ws, user)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(idx, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def put_pointer(self, ws, user, name: str, *, site: str = "",
+                    kind: str = "profile", health: str = "unknown") -> dict:
+        idx = self._load_index(ws, user)
+        now = _now_iso()
+        meta = idx.get(name) or {"name": name, "created": now}
+        meta.update({"name": name, "site": site or meta.get("site", ""),
+                     "kind": kind, "health": health, "rotated": now})
+        meta.setdefault("created", now)
+        idx[name] = meta
+        self._save_index(ws, user, idx)
+        return meta
+
+    def _touch_pointer(self, ws, user, name: str) -> None:
+        idx = self._load_index(ws, user)
+        if name in idx:
+            idx[name]["rotated"] = _now_iso()
+            self._save_index(ws, user, idx)
+
+    def pointer(self, ws, user, name: str) -> dict | None:
+        return self._load_index(ws, user).get(name)
+
+    def list_sessions(self, ws, user) -> list[dict]:
+        return list(self._load_index(ws, user).values())
+
+
+class ObjectStoreWebSessionStore(WebSessionStore):
+    """Swap point for the platform: hydrate/dehydrate move the profile between an
+    ephemeral local dir and object storage (S3/MinIO) per (workspace, user); the lease
+    is a distributed lock. Not implemented in P0.0 - the hosted browser fleet + object
+    storage + streamed login-capture are platform-phase, highest-risk (SPIKE 3)."""
+
+    def __init__(self, *_a, **_k) -> None:
+        raise NotImplementedError(
+            "ObjectStoreWebSessionStore is the platform-phase swap point (spec P0.0-09 / "
+            "procesio-aat-module/09); use LocalWebSessionStore locally.")
+
+    def hydrate(self, ws, user, name): ...
+    def dehydrate(self, ws, user, name, profile_dir): ...
+    def list_sessions(self, ws, user): ...
+    def pointer(self, ws, user, name): ...
+    def _lock_path(self, ws, user, name): ...
+
+
+# -- lease primitives (local lockfile; the platform swaps a distributed lease) --------
+
+def _acquire_lock(lock: Path, *, timeout: float, poll: float) -> int:
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            return os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise LeaseTimeout(f"session lock held: {lock.name}")
+            time.sleep(poll)
+
+
+def _release_lock(fd: int, lock: Path) -> None:
+    try:
+        os.close(fd)
+    finally:
+        try:
+            lock.unlink()
+        except OSError:
+            pass
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")

procesio_cli/tools/connector-builder/CONNECTOR-BUILDER-API-NOTES.md

@@ -0,0 +1,91 @@
+# Connector Builder — API notes (durable)
+
+Hard-won facts about the AI Connector Builder backend so future sessions don't re-derive them. Source repo (the app itself): the AI Connector Builder checkout — see its `documentation/03-API-REFERENCE.md`, `04-PIPELINE-ENGINE.md`, and `deploy/Caddyfile.example`.
+
+## What the platform is
+
+A FastAPI + Postgres app that generates **.NET/C# PROCESIO Custom Action connectors** from API docs via an 8-stage LLM pipeline (LiteLLM, vendor-agnostic). A standalone compiler service runs `dotnet restore/build/pack` and returns a `.nupkg`. Frontend is Next.js. Admin-configurable: prompts, spec modules, examples, validation rules all editable through the API (the "knowledge" endpoints).
+
+## Base URL & routing (verified live 2026-06-30)
+
+- Production host: `https://connector-builder.procesio.app`. Caddy reverse-proxies **`/api/*` → backend** (the `/api` prefix is stripped before reaching FastAPI). So the REST surface documented without a prefix in `03-API-REFERENCE.md` lives under **`/api`** in production.
+  - `GET https://connector-builder.procesio.app/api/auth/me` → works.
+  - The bare host root serves the Next.js frontend (so `GET /health` at the root returns the SPA 404, not the backend health — health is a backend route under `/api` semantics in prod).
+- Dev: backend at `:8000`, frontend at `:3001`. Swagger at `/docs`, OpenAPI at `/openapi.json`.
+- Tool default base = `https://connector-builder.procesio.app/api`; override with env `CONNECTOR_BUILDER_BASE_URL`.
+
+## Auth — BOTH modes are just a bearer token
+
+`backend/app/core/permissions.py::get_current_user` requires `Authorization: Bearer <token>`. If the token **starts with `acb_`** it's looked up as an API key (sha256 hash match in the `api_keys` table); otherwise it's verified as a JWT access token.
+
+So:
+1. **API key**: `Authorization: Bearer acb_...` — verbatim, no login call. Simplest. The key belongs to a specific user (and inherits that user's role).
+2. **Username/password**: `POST /api/auth/login {"email","password"}` → `{"access_token","refresh_token","token_type":"bearer"}`; use the `access_token` as the bearer. (The login field is **`email`**, not `username`.)
+
+The provided account (a platform login email) and the provided API key `acb_...091` both resolve to the **same admin user** (`role: admin`), so the tool can reach every `/admin/*` endpoint. There is no functional difference between the two modes for this account beyond JWT expiry vs. a long-lived key.
+
+Roles: `viewer` / `builder` / `admin`. Most build endpoints need `builder` or `admin`; knowledge/config/users/issues need `admin`.
+
+## Pipeline state machine (drives the agent's `next-step`)
+
+`status` (overall) × `step_status` decide what to call next:
+
+- `pending` → `start-build` (full auto) OR `gather` (manual, synchronous GATHER+CLARIFY).
+- `clarifying` (after gather) → `answer --answers '{...}'` (keys are the question ids) → moves to `planning`.
+- `planning` (plan present) → `approve-plan` (→ generate) or `revise-plan --feedback`.
+- `generating` + `step_status=waiting_user` → review files, then `approve-generate` (→ validate/compile/fix/deliver) or `regenerate` / `regenerate-file`.
+- `validating` + `waiting_user` → `validate-autofix` | `validate-continue` | `validate-return-to-generate`.
+- `failed` → `retry [--from-step N]` (1-3 single stage; 4-5 generate→deliver; ≥6 compile→deliver) or `reset` (only from failed/clarifying/planning).
+- `completed` → `download-artifact`.
+- Jump anywhere with `override-stage --target-step N --target-status running|waiting_user`. **Semantics matter**: `running` clears the target step's own data and re-runs it; `waiting_user` PRESERVES the target step's data and just re-opens its review screen (use this to revisit a plan without wiping it — otherwise `revise-plan` returns "no plan to revise").
+
+## Endpoints worth knowing
+
+- `GET /builds` paginates (`per_page` max 500) with `status` / `archive_status` / `created_by` filters. Each build carries `version_prefix`/`version_build`/`package_version`.
+- `PATCH /builds/{id}/version` only works at **step 3 (Plan) + waiting_user**, and only allows non-decreasing semver.
+- Binary endpoints (stream, not JSON): `GET /builds/{id}/artifact` (the `.nupkg`), `…/files/{file}/download`, `…/files/download-all` (zip). The tool's `download` helper streams these to `--out` and reads the real filename from `Content-Disposition`.
+- `POST /admin/build-selftest` compiles a trivial 2-file C# project end-to-end — a fast health check of the compiler service without burning LLM tokens.
+- **Knowledge** = how the builder itself is tuned. `GET/POST/PUT/DELETE /admin/knowledge/{module_type}/{name}` where `module_type ∈ {prompt, spec_module, example, validation_rule, clarification}`. After editing, `POST /admin/config/reload` to refresh the in-memory cache. Editing `spec_module`/`example`/`prompt` changes generation quality for **all future builds** — this is the deepest improvement loop.
+
+## Errors
+
+Backend returns `{"detail": "..."}` on error (FastAPI default). The compiler internal API returns `{"detail","error_code"}`. The tool maps non-2xx → `ApiError` (`auth_failed` for 401/403, else `api_error`) and surfaces the server `detail` in the message.
+
+## PROCESIO interop (the whole point)
+
+The connector this platform builds is a PROCESIO Custom Action package. The `procesio` tool already installs one:
+
+```
+procesio customaction-upload --file <connector.nupkg>   # POST /api/actions multipart field "package" → {id}
+procesio customaction-list                              # confirm it installed
+procesio customaction-delete --id <actionId>           # uninstall before re-upload
+```
+
+End-to-end loop: `connector-builder download-artifact` → `procesio customaction-upload` → exercise it in a PROCESIO process (run-process / forms / webhooks) → capture failures → feed them back via `connector-builder revise-plan` / `regenerate-file` / (for systemic issues) `knowledge-update` → recompile → re-upload. The **connector-builder agent** encodes this loop; the procesio agent's build-and-test playbook governs the PROCESIO-side testing.
+
+## Tool internals
+
+- Dir name is hyphenated → modules imported by BARE name (`import client`, `from handlers import builds`) with the tool root on sys.path (see `main.py`); tests use an importlib-alias conftest (`cb_*`), NO `tests/__init__.py`, unique `test_cb_*` basenames.
+- `tool.yaml` is GENERATED by `gen_manifest.py` from the live `ACTIONS` dict; never hand-edit actions/args.
+
+## Live-run learnings (first real E2E build, 2026-06-30)
+
+Built a "Send Slack Message" custom action (Slack `chat.postMessage`) end-to-end to exercise the tool+agent. The pipeline ran correctly through create → gather → clarify (10 PROCESIO-aware questions) → plan → generate (6 files, idiomatic SDK code) → compile. Operational facts learned:
+
+- **Synchronous LLM endpoints return 504 at the proxy but COMPLETE server-side.** `gather`, `answers` (PLAN), and `revise-plan` each took longer than Caddy's upstream timeout → without `--wait` the tool got a clean `api_error` 504. The backend kept working. **Handled since v0.2:** pass `--wait` to `gather` / `answer` / `revise-plan` and the tool swallows a 502/503/504 (or client-side timeout) and polls `get-build` to the settled state (`--wait-timeout` default 600s, `--poll-interval` 8s), returning the full build detail with `waited`/`settled` markers. A standalone `wait-build --build-id [--until settled|terminal]` blocks after the fast background stages (`approve-generate`/`retry`/`start-build`) until compile finishes. Robustness detail: the wait guards on `updated_at` advancing past a pre-trigger baseline so a fast poll can't return the stale pre-stage `waiting_user` state. `approve-plan` / `approve-generate` / `retry` return fast (background tasks), so no 504 there.
+- **clarification_questions shape:** `{"questions": [ {id, question, default, options, context, category, required}, ... ]}` — a dict with a `questions` list, NOT a bare list. Each question carries a sensible `default`; answering `{id: default}` for all is a good baseline. The CLARIFY stage is PROCESIO-aware (asks about Credentials_Rest vs secret text, tab structure, FeComponentType, HTTP-200-but-ok=false handling, namespace/class naming).
+- **Generated code quality is high:** correct `Ringhel.Procesio.Action.Core` decorators (`ClassDecorator`, `FETabDecorator`, `FEDecorator` Type=`Credentials_Rest`, `BEDecorator`, `Validator`), `IAction`, `APICredentialsManager`. Matches the procesio-custom-actions skill conventions.
+- **COMPILE blocker — NU1301 restoring the PROCESIO SDK from GitHub Packages.** `compile attempt_1` fails: "Failed to retrieve information about 'Ringhel.Procesio.Action.Core' from remote source 'https://nuget.pkg.github.com/PROCESIO/download/ringhel.procesio.action.core/index.json'." This is **NU1301 (source/package-index access)**, not NU1102 (missing version) — so the pinned version (`1.41.0`) is NOT the cause. `GET /admin/platform-settings` shows `github_packages_pat_set: true` and `POST /admin/platform-settings/test-nuget` returns "PAT is valid" — but test-nuget only checks the ORG index (`/PROCESIO/index.json`), not the package-level download index, so it passing does not prove the SDK package is restorable. `POST /admin/build-selftest` returns "pass" because its trivial 2-file project does NOT reference the SDK, so it never exercises the GitHub Packages restore. **Net: the connector-builder compiler cannot download the PROCESIO SDK package** — a server-side PAT package-scope / egress issue. Fix is platform-side (grant the GitHub Packages PAT read access to the `Ringhel.Procesio.Action.Core` package, or mirror the SDK to a reachable feed), then `retry --from-step 6`. The generated code is already correct and waiting; once restore works, compile→deliver→`download-artifact`→`procesio customaction-upload` completes unchanged.
+- **MSYS path-conversion gotcha (Git Bash on Windows):** the `api --path /admin/...` escape hatch gets its leading-slash path rewritten to `C:/Program Files/Git/admin/...` by MSYS, causing a 404. Run those calls with `MSYS_NO_PATHCONV=1` (or from PowerShell). First-class actions are unaffected (they build the path internally).
+
+## .NET 10 runtime and the knowledge overrides (2026-10-21)
+
+PROCESIO prod runs custom actions on Action-Execution v3 (`net10.0`, `Ringhel.Procesio.Action.Core` 2.1.0) since 2026-10-21, and the builder now generates for it: plan `target_framework: net10.0`, Action-Core 2.1.0 with Newtonsoft.Json 13.0.4 (2.1.0 depends on it, so 13.0.3 is a NU1605 downgrade), compiler image on the .NET 10 SDK. A finished package carries only `lib/net10.0/` and declares one `net10.0` dependency group. Verified end to end on prod: build, compile, upload to PROCESIO, run inside a process, exact outputs. A net8.0 package built earlier still loads on the v3 runtime.
+
+- **Only three libraries are host copies on the v3 runtime:** Action-Core 2.1.0, Newtonsoft.Json 13.0.4 and DocumentFormat.OpenXml 3.5.1. CsvHelper, HtmlAgilityPack, MsgReader, PdfPig and SimMetrics are no longer on the host, so the copy bundled in the package is the one that loads. A host copy still wins over a bundled one of the same name, so code compiled against a different version of those three can throw `MissingMethodException` at run time.
+- **SDK restore from GitHub Packages works** (Action-Core 2.1.0 restores fine); the NU1301 blocker recorded in June is resolved.
+- **Knowledge overrides beat the baked files.** Each knowledge module resolves as: tombstone, else an admin DB override, else the base file baked into the image. An override does not follow later edits of the base, so after changing a base file always check `knowledge-list --module-type <type>` for `"source": "database"` rows of the same name and rewrite them with `knowledge-update --content-file <the committed file>`. Never `knowledge-delete` an override to "fall back" to the base: delete writes a tombstone that hides the base file as well. Read the result back with `knowledge-get` and compare it byte for byte; an earlier override had been stored with every em-dash as mojibake (`—`).
+- **Pipeline config also lives in the DB** (seeded once from `config/pipeline.yaml`). A YAML change only affects a fresh seed; change prod with `update-config --which pipeline --data '{"stages": {...}}'` (merged per stage and validated before saving) and check `get-config --which pipeline` → `budget_warnings`. clarify/plan `max_spec_tokens` below `spec_tokens_total` means those stages silently drop spec modules.
+- **Upload error 261 on a nullable output:** `int?` with `Expects = ExpectedType.Number` compiles but PROCESIO rejects the upload ("ValidatorAttribute.Expects value type does not match the property type"). Use a non-nullable `int` (document what 0 means) or a string. Encoded in the builder's `decorators.md`.
+- **Some API hosts are unreachable from PROCESIO.** A connector can run fine and still time out on its HTTP call because PROCESIO's egress cannot reach that host (seen with `api.agify.io` and the other APIs on its server). Probe a host first from PROCESIO itself: `procesio credential-create --dry-run` with a no-auth `REST API` credential runs a live connection test from PROCESIO's servers.
+- **A credential-free connector pauses at validate** on the warning "No new HttpClient" (the rule expects `Credentials.Client`). It is non-blocking: `validate-continue` proceeds, and a raw `HttpClient` call works on the PROCESIO runtime.

procesio_cli/tools/connector-builder/README.md

@@ -0,0 +1,101 @@
+# connector-builder
+
+Drive the **AI Connector Builder** ([connector-builder.procesio.app](https://connector-builder.procesio.app)) — the platform that turns API documentation into a compiled **PROCESIO Custom Action `.nupkg`** connector through an 8-stage LLM pipeline:
+
+```
+gather → clarify → plan → generate → validate → compile → fix → deliver
+```
+
+This tool is the **REST client** for that platform. It covers the whole build lifecycle, file read/write, artifact/zip download, logs & telemetry, and the admin knowledge base (the prompts/specs/examples that control how every build generates code).
+
+> The compiled `.nupkg` is the bridge to PROCESIO: download it with `download-artifact`, then install it with `procesio customaction-upload --file <nupkg>` to test the connector live. See the **connector-builder agent** for the full build → upload → test → improve loop.
+
+## Auth — two modes, one header
+
+Both modes resolve to an `Authorization: Bearer <token>` header (verified against the backend's `permissions.py` — an API key is just a bearer token starting with `acb_`):
+
+1. **API key** (default): the `acb_...` key, used verbatim.
+2. **Username / password**: `POST /auth/login` → JWT access token. This is the "web-tool" login, done over the REST API (no browser needed — the app exposes the same backend under `/api/*`).
+
+Selection: API key if stored, else username+password. Force with `CONNECTOR_BUILDER_AUTH=apikey|userpass`. Base URL overridable with `CONNECTOR_BUILDER_BASE_URL` (default `https://connector-builder.procesio.app/api`).
+
+### Store credentials
+
+```powershell
+python scripts/set-credential.py connector-builder api-key      # acb_...
+# and/or
+python scripts/set-credential.py connector-builder username     # the platform login email
+python scripts/set-credential.py connector-builder password
+```
+
+(Use `--from-file` on this terminal — interactive paste corrupts secrets.)
+
+## Quick start
+
+```bash
+# Sanity / auth probe
+python scripts/run-tool.py connector-builder check
+
+# 1. Create a build from API docs
+python scripts/run-tool.py connector-builder create-build \
+    --api-url "https://api.example.com/docs" \
+    --user-requirements "A connector that lists and creates orders."
+
+# 2. Gather + clarify → returns clarification questions.
+#    The sync LLM stages (gather/answer/revise-plan) 504 at the proxy but finish
+#    server-side — pass --wait to swallow the 504 and poll to the settled state.
+python scripts/run-tool.py connector-builder gather --build-id <ID> --wait
+
+# 3. Answer the questions → triggers PLAN
+python scripts/run-tool.py connector-builder answer --build-id <ID> \
+    --answers '{"q1":"OAuth2 client credentials","q2":"JSON"}'
+
+# 4. Approve the plan → GENERATE (pauses for review)
+python scripts/run-tool.py connector-builder approve-plan --build-id <ID>
+
+# 5. Accept generated files → VALIDATE → COMPILE → FIX → DELIVER
+python scripts/run-tool.py connector-builder approve-generate --build-id <ID>
+
+# 6. Download the compiled connector
+python scripts/run-tool.py connector-builder download-artifact --build-id <ID> --out connector.nupkg
+```
+
+Prefer the **fully automatic** path? `start-build --build-id <ID>` runs every stage as one background task (no per-stage pauses); poll `get-build` for status.
+
+## Actions
+
+Run `python scripts/run-tool.py connector-builder --help` for the full list. Grouped:
+
+**Auth / identity** — `check`, `whoami`, `list-api-keys`, `create-api-key`, `revoke-api-key`, `set-llm-key`, `delete-llm-key`
+
+**Build lifecycle** — `list-builds`, `get-build`, `create-build`, `start-build`, `gather`, `answer`, `approve-plan`, `revise-plan`, `approve-generate`, `regenerate`, `regenerate-file`, `validate-autofix`, `validate-continue`, `validate-return-to-generate`, `retry`, `override-stage`, `stage-override-options`, `reset`, `set-version`, `archive`, `unarchive`, `wait-build`
+
+> **Surviving the proxy 504:** the synchronous LLM stages (`gather`, `answer`, `revise-plan`) can exceed the gateway timeout and return a 504 while completing server-side. Pass `--wait` (with optional `--wait-timeout` / `--poll-interval`) to swallow that and poll to the settled state. After the background stages (`approve-generate`, `retry`, `start-build`), use `wait-build --build-id <ID>` (optionally `--until terminal`) to block until compile finishes.
+
+**Diagnostics** — `logs`, `events`, `list-messages`, `post-message`, `telemetry`, `list-issues`, `get-issue`, `build-selftest`
+
+**Files & artifact** — `list-file-versions`, `get-file-version`, `update-file`, `set-file-instructions`, `download-file`, `download-all`, `download-artifact`
+
+**Admin / improve-the-builder** — `get-config`, `update-config`, `reload-config`, `knowledge-list`, `knowledge-get`, `knowledge-create`, `knowledge-update`, `knowledge-delete`, `list-users`
+
+**Escape hatch** — `api --method --path --query --body [--out]` for any endpoint not first-classed.
+
+## Feedback loops (how you improve a connector)
+
+| Where it fails | Action |
+|---|---|
+| Plan is wrong | `revise-plan --feedback "..."` |
+| Generated code is wrong | `regenerate-file --filename X --instructions "..."` or `regenerate` |
+| Validation findings | `validate-autofix` / `validate-continue` / `validate-return-to-generate` |
+| Compile failed | `retry --from-step 6` (skips straight to compile→fix→deliver) |
+| Need to jump stages | `override-stage --target-step N --target-status running|waiting_user` |
+| **Builder generates badly across all builds** | edit `knowledge-*` (prompts / spec_module / example / validation_rule / clarification) then `reload-config` |
+
+## Contract
+
+JSON in / JSON out. Success → one JSON object on stdout, exit 0. Failure → `{"error": {"code","message","details"}}`, non-zero exit. Error codes: `invalid_argument` (2), `auth_required`, `auth_failed`, `api_error`, `error`.
+
+## Notes & internals
+
+- `tool.yaml` is **generated** from the handlers by `gen_manifest.py` — edit handlers + the header consts, then rerun `.venv/Scripts/python tools/connector-builder/gen_manifest.py`. A manifest-sync test enforces this.
+- Wire details, gotchas, and the PROCESIO interop are in **CONNECTOR-BUILDER-API-NOTES.md**.

procesio_cli/tools/connector-builder/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: connector-builder
+description: 'AI Connector Builder (connector-builder.procesio.app): turn API documentation into a compiled PROCESIO Custom Action .nupkg connector via an 8-stage LLM pipeline (gather -> clarify -> plan -> generate -> validate -> compile -> fix -> deliver). Drive the whole build lifecycle, read/write generated files, download the .nupkg artifact (to upload to PROCESIO for live testing), inspect logs/telemetry,…'
+---
+
+# connector-builder
+
+AI Connector Builder (connector-builder.procesio.app): turn API documentation into a compiled PROCESIO Custom Action .nupkg connector via an 8-stage LLM pipeline (gather -> clarify -> plan -> generate -> validate -> compile -> fix -> deliver). Drive the whole build lifecycle, read/write generated files, download the .nupkg artifact (to upload to PROCESIO for live testing), inspect logs/telemetry, and edit the builder's own knowledge base (prompts, spec modules, examples, validation rules). Two auth modes, both -> Bearer token: an acb_ API key, or username/password via /auth/login.
+
+## How to call it
+
+```bash
+python scripts/run-tool.py connector-builder <action> [--args]
+# e.g. connector-builder create-build --api-url <docs-url> --user-requirements '...'   (then gather / answer / approve-plan / approve-generate / download-artifact)
+```
+
+One JSON object on stdout for success; `{"error": {"code", "message", "details"}}` and a non-zero exit on failure. Progress and logs go to stderr only.
+
+**Start with `create-build`.**
+
+## Credentials
+
+Stored in the OS credential store, never in files. Missing ones are reported by `python scripts/list-tools.py`.
+
+- `agents-and-tools:connector-builder:api-key` — Connector Builder API key (acb_...). Used verbatim as the bearer token.
+- `agents-and-tools:connector-builder:username` — Login email for username/password auth mode (e.g. user@example.com).
+- `agents-and-tools:connector-builder:password` — Login password for username/password auth mode (-> POST /auth/login -> JWT).
+
+## Actions
+
+### answer
+
+| action | required args | what it does |
+|---|---|---|
+| `answer` | `--build-id`, `--answers` | Submit clarification answers; triggers PLAN. |
+
+### api
+
+| action | required args | what it does |
+|---|---|---|
+| `api` | `--path` | Call any endpoint (method/path/query/body); --out streams binary. |
+
+### approve
+
+| action | required args | what it does |
+|---|---|---|
+| `approve-generate` | `--build-id` | Accept generated files; runs VALIDATE->COMPILE->FIX->DELIVER. |
+| `approve-plan` | `--build-id` | Approve plan; triggers GENERATE (then pauses). |
+
+### archive
+
+| action | required args | what it does |
+|---|---|---|
+| `archive` | `--build-id` | Archive a build (admin). |
+
+### build
+
+| action | required args | what it does |
+|---|---|---|
+| `build-selftest` | — | Compiler health self-test (trivial C#). |
+
+### check
+
+| action | required args | what it does |
+|---|---|---|
+| `check` | — | Connectivity + auth probe (GET /auth/me). |
+
+### create
+
+| action | required args | what it does |
+|---|---|---|
+| `create-api-key` | `--name` | Create an API key (full_key shown only once). |
+| `create-build` | — | Create a build from URL(s) / pasted docs. |
+
+### delete
+
+| action | required args | what it does |
+|---|---|---|
+| `delete-llm-key` | — | Remove the stored LLM provider key. |
+
+### download
+
+| action | required args | what it does |
+|---|---|---|
+| `download-all` | `--build-id`, `--out` | Download all generated files as a zip to --out. |
+| `download-artifact` | `--build-id`, `--out` | Download the compiled .nupkg to --out (upload to PROCESIO). |
+| `download-file` | `--build-id`, `--filename`, `--out` | Download one generated file to --out. |
+
+### events
+
+| action | required args | what it does |
+|---|---|---|
+| `events` | `--build-id` | Per-build pipeline events. |
+
+### gather
+
+| action | required args | what it does |
+|---|---|---|
+| `gather` | `--build-id` | Run GATHER+CLARIFY (profile+questions); --wait survives the 504. |
+
+### get
+
+| action | required args | what it does |
+|---|---|---|
+| `get-build` | `--build-id` | Full build detail (all JSONB fields). |
+| `get-config` | `--which` | Read a config block (pipeline/providers/...). |
+| `get-file-version` | `--build-id`, `--filename`, `--version` | Full content of one file at a specific version. |
+| `get-issue` | `--id` | Full issue-case detail incl. snapshots. |
+
+### knowledge
+
+| action | required args | what it does |
+|---|---|---|
+| `knowledge-create` | `--module-type`, `--name` | Create a new knowledge module. |
+| `knowledge-delete` | `--module-type`, `--name` | Delete a knowledge module. |
+| `knowledge-get` | `--module-type`, `--name` | Get one knowledge module's content. |
+| `knowledge-list` | `--module-type` | List knowledge modules of a type. |
+| `knowledge-update` | `--module-type`, `--name` | Update an existing knowledge module. |
+
+### list
+
+| action | required args | what it does |
+|---|---|---|
+| `list-api-keys` | — | List your API keys. |
+| `list-builds` | — | List builds (paginated, filterable). |
+| `list-file-versions` | `--build-id` | Version metadata for every file in a build (no content). |
+| `list-issues` | — | List issue cases (failures), filterable. |
+| `list-messages` | `--build-id` | Chat/system messages for a build. |
+| `list-users` | — | List all users (admin). |
+
+### logs
+
+| action | required args | what it does |
+|---|---|---|
+| `logs` | `--build-id` | Per-build stage logs (model/cost/token breakdown). |
+
+### override
+
+| action | required args | what it does |
+|---|---|---|
+| `override-stage` | `--build-id`, `--target-step`, `--target-status` | Jump the build to a target step/status. |
+
+### post
+
+| action | required args | what it does |
+|---|---|---|
+| `post-message` | `--build-id`, `--step`, `--content` | Post a chat message to a build/step. |
+
+### regenerate
+
+| action | required args | what it does |
+|---|---|---|
+| `regenerate` | `--build-id` | Regenerate files with per-file/general instructions. |
+| `regenerate-file` | `--build-id`, `--filename`, `--instructions` | Regenerate a single file with instructions. |
+
+### reload
+
+| action | required args | what it does |
+|---|---|---|
+| `reload-config` | — | Reload all YAML config + knowledge cache. |
+
+### reset
+
+| action | required args | what it does |
+|---|---|---|
+| `reset` | `--build-id` | Reset a failed/clarifying/planning build to pending. |
+
+### retry
+
+| action | required args | what it does |
+|---|---|---|
+| `retry` | `--build-id` | Retry the pipeline from a step (or last failed). |
+
+### revise
+
+| action | required args | what it does |
+|---|---|---|
+| `revise` | `--build-id` | Re-open a COMPLETED build to the generate pause for a small fix (then regenerate-file + approve-generate); bumps the version. |
+| `revise-plan` | `--build-id`, `--feedback` | Revise the plan with free-text feedback. |
+
+### revoke
+
+| action | required args | what it does |
+|---|---|---|
+| `revoke-api-key` | `--id` | Revoke an API key by id. |
+
+### set
+
+| action | required args | what it does |
+|---|---|---|
+| `set-file-instructions` | `--build-id`, `--filename`, `--instructions` | Save per-file regeneration instructions. |
+| `set-llm-key` | `--api-key`, `--provider` | Set the LLM provider key that powers builds. |
+| `set-version` | `--build-id`, `--major`, `--minor`, `--patch` | Set Major.Minor.Patch (at Plan/waiting_user). |
+
+### stage
+
+| action | required args | what it does |
+|---|---|---|
+| `stage-override-options` | — | Valid stage-override targets for override-stage. |
+
+### start
+
+| action | required args | what it does |
+|---|---|---|
+| `start-build` | `--build-id` | Run the FULL pipeline as a background task. |
+
+### telemetry
+
+| action | required args | what it does |
+|---|---|---|
+| `telemetry` | — | Cross-build LLM telemetry (cost/tokens/latency), filterable. |
+
+### unarchive
+
+| action | required args | what it does |
+|---|---|---|
+| `unarchive` | `--build-id` | Unarchive a build (admin). |
+
+### update
+
+| action | required args | what it does |
+|---|---|---|
+| `update-config` | `--which` | Update a config block from JSON. |
+| `update-file` | `--build-id`, `--filename` | Overwrite a file's content (inline or from --content-file). |
+
+### validate
+
+| action | required args | what it does |
+|---|---|---|
+| `validate-autofix` | `--build-id` | Auto-fix validation findings. |
+| `validate-continue` | `--build-id` | Continue past validation to COMPILE. |
+| `validate-return-to-generate` | `--build-id` | Return from VALIDATE back to GENERATE. |
+
+### wait
+
+| action | required args | what it does |
+|---|---|---|
+| `wait-build` | `--build-id` | Poll get-build until settled/terminal (use after approve-generate/retry). |
+
+### whoami
+
+| action | required args | what it does |
+|---|---|---|
+| `whoami` | — | Full current-user record (GET /auth/me). |
+
+---
+
+Generated from `tools/connector-builder/tool.yaml` by `scripts/build-tool-skill.py`. Do not edit by hand — change the manifest and regenerate.

procesio_cli/tools/connector-builder/__init__.py

@@ -0,0 +1,7 @@
+"""connector-builder tool package marker.
+
+The dir name has a hyphen, so this tool's own modules are imported by BARE name
+(``import client``, ``from handlers import builds``) with the tool root on
+sys.path at runtime — see main.py. This file just makes the folder importable
+as ``tools.connector_builder`` is NOT possible (hyphen); kept for parity.
+"""