@waron97/prbot 3.2.0 → 3.3.0

package/README.md

@@ -194,7 +194,7 @@ prbot update
 
 ## agrippa
 
-Syncs Odoo workflow phase Python code and MFA records between the local filesystem and the RIP API. Tracks changes via checksums and detects conflicts before overwriting.
+Syncs Odoo workflow phase Python code, MFA records, process-builder wizards, and long-running processes (LRPs) between the local filesystem and the RIP / Process Builder / Symphony APIs. Tracks changes via checksums and detects conflicts before overwriting.
 
 Credentials are inherited from the global prbot config (`~/.config/prbot/config`). Override per-workspace in `agrippa.yaml`.
 
@@ -208,9 +208,9 @@ agrippa init
 
 ### `agrippa clone`
 
-Clones all `from_code` phases for a selected workflow, a single MFA, or a **process-builder wizard**, into the workspace. Writes files to disk and registers them in `agrippa.yaml`. With no flag, prompts for the object type (MFA / Phase / Process Builder).
+Clones all `from_code` phases for a selected workflow, a single MFA, a **process-builder wizard**, or a **long-running process (LRP)**, into the workspace. Writes files to disk and registers them in `agrippa.yaml`. With no flag, prompts for the object type (MFA / Phase / Process Builder / Long Running Process).
 
-A wizard is downloaded and **decomposed** into editable files (`structure.yaml`, `process.yaml`, `scripts/`, `pages/`, manifest); see [`agrippa pb`](#agrippa-pb) and [`agrippa-pb.md`](agrippa-pb.md).
+A wizard or LRP is downloaded and **decomposed** into editable files (`structure.yaml`, `process.yaml`, `scripts/`, `pages/`, manifest) — LRPs share the same layout minus `pages/` (LRPs have no user tasks); see [`agrippa pb`](#agrippa-pb) and [`agrippa-pb.md`](agrippa-pb.md).
 
 ```bash
 agrippa clone
@@ -219,18 +219,21 @@ agrippa clone --mfa
 agrippa clone --phase --id 123 --path my-workflow/
 agrippa clone --pb                          # select a wizard
 agrippa clone --pb --name ml_review_billing --path my-wizard/
+agrippa clone --lrp                         # live search LRPs by name
+agrippa clone --lrp --name B2WA_ml_IFS_passive_trigger --path my-lrp/
 ```
 
 Options:
 
-| Flag                   | Description                                                   |
-| ---------------------- | ------------------------------------------------------------- |
-| `--phase`              | Clone a phase (select a workflow)                             |
-| `--mfa`                | Clone an MFA record                                           |
-| `--pb`                 | Clone a process-builder wizard                                |
-| `--id <id>`            | Skip selection, clone by ID (phase/mfa)                       |
-| `--name <document_id>` | Skip selection, clone a wizard by `document_id` (with `--pb`) |
-| `--path <path>`        | Destination path (base dir for phases/wizard, file for MFA)   |
+| Flag              | Description                                                                |
+| ----------------- | --------------------------------------------------------------------------- |
+| `--phase`         | Clone a phase (select a workflow)                                          |
+| `--mfa`           | Clone an MFA record                                                        |
+| `--pb`            | Clone a process-builder wizard                                             |
+| `--lrp`           | Clone a long-running process                                               |
+| `--id <id>`       | Skip selection, clone by ID (phase/mfa)                                    |
+| `--name <name>`   | Skip selection: `document_id` (with `--pb`) or process name (with `--lrp`) |
+| `--path <path>`   | Destination path (base dir for phases/wizard/lrp, file for MFA)            |
 
 ### `agrippa pull`
 
@@ -238,7 +241,7 @@ Fetches remote code for all tracked entries and shows what changed. Classifies e
 
 After pulling, also checks tracked workflows for newly added `from_code` phases and auto-clones any not yet present locally.
 
-Tracked **process-builder wizards** are also refreshed from upstream: the local project is re-decomposed from the latest payload (orphan script/page files pruned), with the same `fast-forward`/`conflict` classification (based on the wizard's upstream `updated_date` vs. the last pulled state). The current local state is backed up to `.backup/<timestamp>/<path>/local.json` first.
+Tracked **process-builder wizards** and **long-running processes** are also refreshed from upstream: the local project is re-decomposed from the latest payload (orphan script files pruned; PB wizards also prune orphan pages), with the same `fast-forward`/`conflict` classification (PB: upstream `updated_date`; LRP: re-resolved-by-name payload checksum vs. the last pulled state — LRPs have no stable id, so every pull re-resolves the current id/tenantId by name first). The current local state is backed up to `.backup/<timestamp>/<path>/local.json` first.
 
 ```bash
 agrippa pull
@@ -246,14 +249,14 @@ agrippa pull
 
 ### `agrippa push`
 
-Pushes local file changes back to RIP (phases/MFAs) and to the Process Builder API (wizards). Backs up current remote state to `.backup/<timestamp>/` before overwriting. Same conflict detection as pull, with the concern inverted.
+Pushes local file changes back to RIP (phases/MFAs), the Process Builder API (wizards), and Symphony (long-running processes). Backs up current remote state to `.backup/<timestamp>/` before overwriting. Same conflict detection as pull, with the concern inverted. LRP entries are located by **name**, not id (the Symphony id changes on every save), re-resolving the current id/tenantId immediately before saving.
 
-Pushing a wizard saves it as a **draft**; publish it so live consumers see the change with `--publish` (auto) or answer the prompt. Page edits (`pages/`) are saved independently of the whole-wizard save, mirroring the UI.
+Pushing a wizard saves it as a **draft**; publish it so live consumers see the change with `--publish` (auto) or answer the prompt. Page edits (`pages/`) are saved independently of the whole-wizard save, mirroring the UI. Pushing an LRP saves the BPMN via Symphony's `tabulator` PATCH; **deploy** it (the LRP analog of publish) the same way — `--publish`/`--skip-publish` double as auto-deploy/never-deploy for LRPs too.
 
 ```bash
-agrippa push                 # prompts whether to publish each pushed wizard
-agrippa push --publish       # auto-publish pushed wizards
-agrippa push --skip-publish  # never publish (no prompt)
+agrippa push                 # prompts whether to publish/deploy each pushed wizard/LRP
+agrippa push --publish       # auto-publish wizards, auto-deploy LRPs
+agrippa push --skip-publish  # never publish/deploy (no prompt)
 ```
 
 ### `agrippa diff [path]`
@@ -286,7 +289,7 @@ agrippa repair
 
 ### `agrippa pb`
 
-Local editing helpers for a **cloned process-builder wizard** (no network — they edit the decomposed files in place). Each operates on **one** wizard, resolved by `--pb <document_id>`, single-entry auto-select, or a fuzzy prompt.
+Local editing helpers for a **cloned process-builder wizard or long-running process** (no network — they edit the decomposed files in place; both share the same decomposed layout and BPMN engine). Each operates on **one** wizard/LRP, resolved by `--pb <document_id_or_name>` (name for LRPs, since they have no `document_id`), single-entry auto-select, or a fuzzy prompt.
 
 These commands exist mainly so an **AI agent** can add/remove/connect blocks without hand-editing the multi-thousand-line `structure.yaml`. Human users typically edit blocks in the UI instead. Full agent-facing guide (also usable as a workspace `CLAUDE.md`): [`agrippa-pb.md`](agrippa-pb.md).
 
@@ -307,4 +310,9 @@ agrippa pb ls --pb ml_review_billing
 agrippa pb add --type scriptTask --name "Check pod" --pb ml_review_billing
 agrippa pb connect --from ScriptTask_x --to ExclusiveGateway_y --pb ml_review_billing
 agrippa pb format --pb ml_review_billing
+
+agrippa pb ls --pb B2WA_ml_IFS_passive_trigger        # LRP, resolved by name
+agrippa pb add --type serviceTask --name "Call SAP" --pb B2WA_ml_IFS_passive_trigger
 ```
+
+`userTask` (pages) can't be added to an LRP project — LRPs never have user tasks.

package/agrippa-pb.md

@@ -1,14 +1,14 @@
-# Instructions for working with Phases, MFAs, and Process-Builder wizards
+# Instructions for working with Phases, MFAs, Process-Builder wizards, and LRPs
 
-You are my coding assistant developing MFAs, phases, and process-builder wizards for
-our Odoo CRM. Follow instructions precisely, without doing fixes or enhancements
-outside the scope of your instructions.
+You are my coding assistant developing MFAs, phases, process-builder wizards, and
+long-running processes (LRPs) for our Odoo CRM. Follow instructions precisely, without
+doing fixes or enhancements outside the scope of your instructions.
 
 This workspace is an **agrippa** workspace: a local checkout of Odoo code synced via
 the `agrippa` CLI. **You (the agent) never run `agrippa clone`, `agrippa pull`, or
 `agrippa push`** — those are human-only operations. You edit local files, and for
-wizards you also drive the `agrippa pb` editing commands (below). A human reviews and
-syncs.
+wizards and LRPs you also drive the `agrippa pb` editing commands (below). A human
+reviews and syncs.
 
 ---
 
@@ -57,35 +57,85 @@ match the result whose `next_phase` is X and use its `code_values`.
 
 ### Code inside phases and MFAs
 
-The following applies to both phases and MFAs.
-
-Some global utilities are made available inside the script, such as:
-
-- `json_dumps` (from `json.dumps`)
-- `json_loads` (from `json.loads`)
-- `datetime` (root-level import from datetime)
-- `dateutil` (root-level import from dateutil)
-- `request` (from `requests.request`)
-- `log` (logging method)
-- `format_exc` (from `traceback.format_exc`)
-- `first` (from `fields.first`)
-- `case_id` (phases only — the current `helpdesk.ticket`)
-
-The value of the `result` variable is used to construct the HTTP response.
-The `make_response` helper allows returning error states, e.g.
-`result = make_response((500, 500), "Custom error message")`.
-
-Some patterns not allowed in Odoo's `safe_eval`:
-
-- f-strings
-- imports
-- lambdas inside functions (`def` inside another function is fine)
-- doc strings (you cannot write to dunder fields)
-
-Notably unavailable:
-
-- `getattr`
-- `setattr`
+Phases and MFAs both run stored Python through Odoo 15 `safe_eval` (mode `exec`), but
+they run in **different environments with different globals**. The shared sandbox rules
+come first; the per-environment globals follow.
+
+#### Shared sandbox rules (apply to both)
+
+Patterns **not allowed** by `safe_eval`:
+
+- **`import`** — forbidden outright.
+- **f-strings** — do not use them; use `"...{}".format(...)` instead. (The current
+  runtime's opcode whitelist technically permits them, but team convention and observed
+  failures mean you must avoid them.)
+- **attribute assignment** (`obj.attr = x`) — forbidden (`STORE_ATTR` is blocked). You
+  cannot set attributes; write through the ORM (`record.write({...})`) instead.
+- **dunder names** — any name containing `__` (e.g. `__class__`) is rejected. This is why
+  you cannot write doc strings.
+- **`getattr` / `setattr` / `eval`** — not in the builtins, so unavailable.
+
+Patterns that **are** allowed (but with a sharp limit):
+
+- **lambdas and nested `def` are creatable, but cannot form closures.** A lambda/nested
+  function may reference only its **own parameters, module globals** (`env` etc.) **and
+  constants**. It must **not** capture a variable from the enclosing function — the
+  closure-cell opcodes (`LOAD_DEREF`/`STORE_DEREF`/`LOAD_CLOSURE`/`MAKE_CELL`) are not
+  whitelisted, so a closure fails validation.
+    - ✅ works: `recs.filtered(lambda r: r.wizard_result == "CANCEL")` — no captured locals
+    - ❌ fails: `recs.filtered(lambda r: r.x == target)` — `target` is an enclosing local
+    - In practice nested functions are rarely usable, since they almost always close over
+      local state. Self-contained `.filtered(lambda r: ...)` predicates are the common
+      legitimate use and appear throughout real phase code.
+
+#### Phase environment (`symple.triplet.phase`)
+
+Phase code runs against a full Odoo "server action" context. Globals available:
+
+- `env` — the **full Odoo ORM** (`env["model"].sudo().search/create/write/browse`)
+- `case_id` — the current `helpdesk.ticket`
+- `Command` — x2many command namespace
+- `ValidationError` — raise to abort with a warning
+- `request` (= `requests.request`), for outbound HTTP
+- `json_dumps` (= `json.dumps`), `json_load` (= `json.load` — note: **not** `json_loads`)
+- `time`, `datetime`, `dateutil`, `timezone`, `float_compare`, `OrderedDict`
+- `b64encode`, `b64decode`
+- `log(message, level='info')`, `format_exc` (= `traceback.format_exc`), `first`
+  (= `fields.first`), `uid`, `user`
+
+There is **no** `make_response` in phases.
+
+**Returning a result:** assign `result` as a **string** — it must match one of the phase's
+`code_values` in `workflow.yml` (e.g. `result = "RES1"`). It is **not** a dict. The string
+is matched against `result.code.configurator` to pick the outgoing edge.
+
+**Reporting errors:** write the message onto the case, conventionally
+`case_id.write({"info_message": "..."})` (`error_message` also exists but `info_message`
+is the prevailing choice).
+
+**Case helpers** (defined on `helpdesk.ticket` in `sorgenia_tools`):
+
+- `case_id.kv_store()` — the per-case key/value store (see below).
+- `case_id.last_staging("<process_name>")` — returns the latest
+  `symple.pb.process.data` for that process on the case, raising `ValidationError` if
+  none exists. Prefer this over searching `symple.pb.process.data` by hand.
+
+#### MFA environment (RIP)
+
+MFA code runs to build an HTTP response, with a much smaller context. Globals available:
+
+- `env` — the Odoo ORM
+- `make_response` — build a response, e.g.
+  `result = make_response((500, 500), "Custom error message")`
+- `logger` — a standard Python logger
+- `result` — assign the response payload (a recordset or JSON-serialisable content); it
+  is consumed to construct the HTTP response
+- the incoming request data: `method`, `model`, `records`, `user`, `args`, `headers`,
+  `body`, `httprequest`
+- `datetime`, `dateutil`
+
+MFAs have **no** `case_id`, `Command`, `ValidationError`, `json_dumps`, `first`, `log`,
+or `format_exc` by default.
 
 ### Communication between phases
 
@@ -108,26 +158,42 @@ records.
 
 ---
 
-## Process-builder wizards
-
-A wizard is a BPMN process the CRM runs as a guided flow. Locally it has been
-**decomposed** into editable files. For wizards you are expected to **drive the
-`agrippa pb` commands** for structural changes — they hide BPMN id generation, the
-nested-YAML graph, dangling-edge cleanup, and the script/page/manifest bookkeeping you
-would otherwise get wrong by hand.
+## Process-builder wizards and long-running processes (LRPs)
+
+A wizard or LRP is a BPMN process the CRM runs as a guided flow (wizards) or a
+long-running background process (LRPs). Both are the **same underlying Activiti/
+Symphony BPMN XML**, so locally they share **one** decomposed layout and one `pb`
+editing suite — everything below applies to both unless a difference is called out.
+For wizards/LRPs you are expected to **drive the `agrippa pb` commands** for
+structural changes — they hide BPMN id generation, the nested-YAML graph,
+dangling-edge cleanup, and the script/page/manifest bookkeeping you would otherwise
+get wrong by hand.
+
+**LRP-specific differences:**
+
+- **No pages.** LRPs never contain `userTask`. `pb add --type userTask` errors out on
+  an LRP project.
+- **Selector is `name`, not `document_id`.** LRPs have no stable id — the Symphony id
+  changes on every save — so `--pb <name>` (not a `document_id`) is how you target an
+  LRP project. `pb ls`/error messages show `name` when `document_id` is absent.
+- **A few extra node types show up more often**: `intermediateCatchEvent`,
+  `intermediateThrowEvent`, `callActivity`, `parallelGateway`, `eventBasedGateway` (see
+  Node types below) — these exist for PBs too but are common in LRPs.
+- Publishing is called **deploy** for LRPs (same human-only `agrippa push
+  --publish`/`--skip-publish` flow as wizard publish — not a `pb` command).
 
 > **You never run `agrippa push` or `agrippa pull`.** You only edit local files and run
-> the local, read/write `agrippa pb` subcommands. A human syncs and publishes.
+> the local, read/write `agrippa pb` subcommands. A human syncs and publishes/deploys.
 
 ### Decomposed project layout
 
 ```
-<wizard-dir>/
+<wizard-or-lrp-dir>/
   process.yaml      identity + top-level flags (envelope)
   structure.yaml    THE graph: nodes hold their outgoing `edges` and nested
                     `nodes` (for subProcess/transaction); inline geometry
   scripts/NNNN_*.js one scriptTask body each (byte-exact)
-  pages/<formKey>.yml one userTask page object each
+  pages/<formKey>.yml one userTask page object each (PB only — LRPs have no pages/)
   .agrippa-pb.json  manifest: scalars, namespaces, id↔file maps (do not hand-edit)
 ```
 
@@ -149,17 +215,21 @@ A node looks like:
 ```
 
 Node types: `startEvent`, `endEvent`, `boundaryEvent`, `exclusiveGateway`,
-`scriptTask`, `serviceTask`, `userTask`, `subProcess`, `transaction`.
+`scriptTask`, `serviceTask`, `userTask` (PB only), `subProcess`, `transaction`,
+`intermediateCatchEvent`, `intermediateThrowEvent`, `callActivity`,
+`parallelGateway`, `eventBasedGateway`.
 
 ### Your loop
 
 ```
 agrippa pb ls            # discover node/edge ids
 agrippa pb add / rm / connect / disconnect / set-default   # change the graph
+agrippa pb lint          # check for structural issues before handing off
 # STOP. Do NOT format. Do NOT push. Report back to the human (see Formatting below).
 ```
 
-Every `pb` command targets **one** wizard. **Always pass `--pb <document_id>`** so you
+Every `pb` command targets **one** wizard or LRP. **Always pass
+`--pb <document_id_or_name>`** (a wizard's `document_id`, or an LRP's `name`) so you
 never hit an interactive prompt.
 
 ### Commands
@@ -167,7 +237,7 @@ never hit an interactive prompt.
 #### `pb ls` — discover ids
 
 ```bash
-agrippa pb ls --pb <document_id>
+agrippa pb ls --pb <document_id_or_name>
 ```
 
 Flat list of every node with its id, type, name, parent (if nested), and outgoing
@@ -186,17 +256,21 @@ ExclusiveGateway_1lghfov  (exclusiveGateway)  "eg err"
 #### `pb add` — add a node
 
 ```bash
-agrippa pb add --type scriptTask --name "Check pod" --pb <document_id>
-agrippa pb add --type userTask   --name "Review"    --pb <document_id>
-agrippa pb add --type subProcess --name "Retry loop" --pb <document_id>
-agrippa pb add --type scriptTask --name "Inner" --parent SubProcess_x --pb <document_id>
+agrippa pb add --type scriptTask --name "Check pod" --pb <document_id_or_name>
+agrippa pb add --type userTask   --name "Review"    --pb <document_id_or_name>
+agrippa pb add --type subProcess --name "Retry loop" --pb <document_id_or_name>
+agrippa pb add --type scriptTask --name "Inner" --parent SubProcess_x --pb <document_id_or_name>
 ```
 
 Prints the new node id. Side effects, handled for you:
 
 - `scriptTask` → creates an **empty** `scripts/NNNN_<slug>.js`; edit that file for the body.
 - `userTask` → creates a **stub** `pages/<slug>.yml` + a manifest entry (no page content).
+  **PB only** — rejected with an error on an LRP project (LRPs have no user tasks).
 - `subProcess`/`transaction` → empty container; add children with `--parent <its-id>`.
+- new event/gateway types (`intermediateCatchEvent`, `intermediateThrowEvent`,
+  `callActivity`, `parallelGateway`, `eventBasedGateway`) → sized/laid out like their
+  closest existing counterpart, no extra scaffold files.
 
 The node is added **disconnected** with placeholder geometry. Connect it next.
 
@@ -204,7 +278,7 @@ The node is added **disconnected** with placeholder geometry. Connect it next.
 instead of adding it disconnected:
 
 ```bash
-agrippa pb add --type scriptTask --name "New" --from A --to End --pb <document_id>
+agrippa pb add --type scriptTask --name "New" --from A --to End --pb <document_id_or_name>
 ```
 
 Requires **exactly one** existing edge `A → End` already (errors if there's none, or
@@ -216,7 +290,7 @@ new-node → `End`. `--parent` is implied by `A`/`End`'s container, so don't pas
 #### `pb rm` — remove a node
 
 ```bash
-agrippa pb rm --id ScriptTask_0mmmti4 --pb <document_id>
+agrippa pb rm --id ScriptTask_0mmmti4 --pb <document_id_or_name>
 ```
 
 Removes the node (and, for a container, its children), **every edge pointing at it**
@@ -227,35 +301,58 @@ manifest entries. No dangling references left behind.
 
 ```bash
 # plain sequence
-agrippa pb connect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
+agrippa pb connect --from ScriptTask_a --to ScriptTask_b --pb <document_id_or_name>
 
-# gateway branch with a condition
+# named branch (required when the source has 2+ outgoing flows and this is non-default)
 agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_b \
-  --condition '${isAlive}' --pb <document_id>
+  --name "alive" --condition '${isAlive}' --pb <document_id_or_name>
 
-# the gateway's fallback branch
+# the gateway's fallback branch (default needs no name)
 agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err \
-  --default --pb <document_id>
+  --default --pb <document_id_or_name>
 ```
 
 A flow's id is printed. Conditions default to `xsi:type="tFormalExpression"`
-(override with `--condition-type`). **Gateway rule** (enforced by Activiti, warned by
-this command): an `exclusiveGateway` with more than one outgoing flow must have
-**exactly one** `--default` flow, and **every other** outgoing flow must carry a
-`--condition`. Heed the `!` warnings `connect` prints.
+(override with `--condition-type`). **Rules** (warned by this command and by `pb lint`):
+
+- An `exclusiveGateway` with more than one outgoing flow must have **exactly one**
+  `--default` flow, and **every other** outgoing flow must carry a `--condition`.
+- Any node with more than one outgoing flow: every **non-default** flow must have a
+  `--name` (operators need labels to distinguish branches at runtime).
+- Only `exclusiveGateway` may have more than one **incoming** flow.
+- An `exclusiveGateway` may not have both multiple incoming **and** multiple outgoing
+  flows — pick one direction (merging or splitting), not both.
+
+Heed the `!` warnings `connect` prints.
 
 #### `pb disconnect` — remove a flow
 
 ```bash
-agrippa pb disconnect --id SequenceFlow_1lso8x0 --pb <document_id>
-agrippa pb disconnect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
+agrippa pb disconnect --id SequenceFlow_1lso8x0 --pb <document_id_or_name>
+agrippa pb disconnect --from ScriptTask_a --to ScriptTask_b --pb <document_id_or_name>
+```
+
+#### `pb lint` — check for structural issues
+
+```bash
+agrippa pb lint --pb <document_id_or_name>
 ```
 
+Runs all diagram rules and prints any violations. Exits 1 if issues found. Run after
+every batch of structural edits before handing off to a human. Rules checked:
+
+- `exclusiveGateway` default/condition rule (2+ outgoing → one default, rest conditioned)
+- Non-default outgoing flows must have a name when the source has 2+ outgoing flows
+- Only `exclusiveGateway` may have multiple incoming flows
+- `exclusiveGateway` may not have both multiple incoming and multiple outgoing flows
+
+`pb format` and `pb connect` also surface the same warnings inline.
+
 #### `pb set-default` — change a gateway's default flow
 
 ```bash
-agrippa pb set-default --id SequenceFlow_b --pb <document_id>
-agrippa pb set-default --from ExclusiveGateway_g --to EndEvent_err --pb <document_id>
+agrippa pb set-default --id SequenceFlow_b --pb <document_id_or_name>
+agrippa pb set-default --from ExclusiveGateway_g --to EndEvent_err --pb <document_id_or_name>
 ```
 
 Flips an **already-existing** flow to be its source gateway's `default`, by edge id or
@@ -268,7 +365,7 @@ non-default flow left without one).
 #### `pb preview` — visual check
 
 ```bash
-agrippa pb preview --pb <document_id> --out /tmp/wizard.svg
+agrippa pb preview --pb <document_id_or_name> --out /tmp/wizard.svg
 ```
 
 Renders the current geometry to an SVG so a human can eyeball the result. Safe to run.
@@ -276,8 +373,8 @@ Not byte-faithful to the real renderer — a sanity check only.
 
 ### Formatting — a human decision, do NOT run it yourself
 
-`agrippa pb format` re-lays-out the **entire** wizard with an automatic algorithm.
-On an existing wizard this **discards the human's hand-tuned layout** and produces a
+`agrippa pb format` re-lays-out the **entire** wizard/LRP with an automatic algorithm.
+On an existing project this **discards the human's hand-tuned layout** and produces a
 drastically different diagram. That may or may not be acceptable — **only the human
 decides.**
 
@@ -286,9 +383,9 @@ positions, and **you stop there**. Report to the human what you changed and that
 new blocks need positioning, then let them choose one of:
 
 1. **Run `agrippa pb format`** themselves — accepts a full automatic re-layout of the
-   whole wizard (existing arrangement is lost), or
-2. **Position the new blocks by hand in the UI** after a human pushes the change —
-   preserving the existing layout.
+   whole project (existing arrangement is lost), or
+2. **Position the new blocks by hand in the UI** after a human pushes/deploys the
+   change — preserving the existing layout.
 
 Never run `pb format` unless the human explicitly tells you to, with that trade-off
 understood.
@@ -324,7 +421,8 @@ graph (`pb ls`) first if so.
 
 ```bash
 agrippa pb add --type exclusiveGateway --name "alive?" --pb W   # → ExclusiveGateway_g
-agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_ok  --condition '${isAlive}' --pb W
+agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_ok \
+  --name "alive" --condition '${isAlive}' --pb W
 agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err --default --pb W
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@waron97/prbot",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "description": "",
     "main": "index.js",
     "scripts": {

package/src/agrippa/commands/clone.js

@@ -7,12 +7,16 @@ import { describeWorkflow, getPhasesByWorkflow, listMfas, listWorkflows } from '
 import { computeChecksum } from '../lib/checksum.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
 import { defaultMfaPath, toSlug, writeCodeFile, writeWorkflowDoc } from '../lib/workspace.js';
+import { cloneLrp } from './cloneLrp.js';
 import { clonePb } from './clonePb.js';
 
 async function clone(opts) {
     if (opts.pb) {
         return clonePb(opts);
     }
+    if (opts.lrp) {
+        return cloneLrp(opts);
+    }
 
     const config = readConfig();
     loadEffectiveEnv(config);
@@ -26,11 +30,13 @@ async function clone(opts) {
                 { name: 'MFA', value: 'mfa' },
                 { name: 'Phase', value: 'phase' },
                 { name: 'Process Builder', value: 'pb' },
+                { name: 'Long Running Process', value: 'lrp' },
             ],
         });
     }
-    // Process-builder wizards have their own clone flow (PB_URL, recompose verify).
+    // Process-builder wizards and LRPs have their own clone flow (recompose verify).
     if (objectType === 'pb') return clonePb(opts);
+    if (objectType === 'lrp') return cloneLrp(opts);
 
     const ripUrl = process.env.RIP_URL;
     if (!ripUrl)

package/src/agrippa/commands/cloneLrp.js

@@ -0,0 +1,114 @@
+import search from '@inquirer/search';
+import inquirer from 'inquirer';
+import { getToken } from '../../lib/auth.js';
+import { computeChecksum } from '../lib/checksum.js';
+import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
+import { getLrpXml, listLrps, resolveLrpByName } from '../lib/lrpApi.js';
+import { comparePayload, decompose, recompose, stableStringify } from '../lib/pbProject.js';
+import { projectReader, writeProject } from '../lib/pbWorkspace.js';
+
+// Clone a long-running process (LRP). Structurally identical to a PB clone
+// (same decompose/recompose/checksum machinery — LRPs are plain Activiti BPMN
+// too), but selection and identity are name-based: the tabulator `id` changes
+// on every save/version bump (verified live — a re-fetched id differs from a
+// previously captured one for the same process), so it can never be used as
+// a stable workspace key the way PB's guid is.
+async function cloneLrp(opts) {
+    const config = readConfig();
+    loadEffectiveEnv(config);
+
+    if (!process.env.IMPORTEXPORT_URL) {
+        throw new Error(
+            'IMPORTEXPORT_URL is not configured. Run `prbot init` or set it in agrippa.yaml.'
+        );
+    }
+
+    const token = await getToken();
+
+    // Selection: by --name (exact) or interactive server-side search (LRPs
+    // are searched server-side by name — see listLrps — not fetched-all-then-
+    // fuzzy-filtered like PBs).
+    let chosen;
+    if (opts.name) {
+        chosen = await resolveLrpByName(token, opts.name);
+    } else {
+        console.log('Fetching long-running process list...');
+        const initial = await listLrps(token, null);
+        let controller = null;
+        chosen = await search({
+            message: 'Select a long-running process:',
+            source: async (input) => {
+                if (!input) return initial.map((p) => ({ name: p.name, value: p }));
+                if (controller) controller.abort();
+                controller = new AbortController();
+                try {
+                    const list = await listLrps(token, input, controller.signal);
+                    return list.map((p) => ({ name: p.name, value: p }));
+                } catch {
+                    return initial.map((p) => ({ name: p.name, value: p }));
+                }
+            },
+        });
+    }
+
+    // Destination directory.
+    let dest = opts.path ?? null;
+    if (!dest) {
+        const { inputPath } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'inputPath',
+                message: 'Destination directory:',
+                default: chosen.name.replace(/^B2WA_/, ''),
+            },
+        ]);
+        dest = inputPath;
+    }
+
+    console.log(`Fetching "${chosen.name}"...`);
+    const { xml, description } = await getLrpXml(token, chosen.id);
+    const payload = { built_page: xml };
+
+    const { files } = decompose(payload);
+    writeProject(dest, files);
+
+    const scriptCount = Object.keys(files).filter((p) => p.startsWith('scripts/')).length;
+    console.log(`Cloned to ${dest}/  (${scriptCount} script(s)).`);
+
+    // Prove the clone reconstructs the original XML (0-loss bar A). LRPs have
+    // no `pages` at all — recompose always synthesizes `pages: []`, which
+    // comparePayload (shared with PB, where it's meaningful) would otherwise
+    // flag as noise on every single LRP clone.
+    const rebuilt = recompose(projectReader(dest));
+    const diffs = comparePayload(payload, rebuilt).filter((d) => !d.startsWith('pages:'));
+    if (diffs.length) {
+        console.warn('WARNING: round-trip verification found differences:');
+        diffs.forEach((d) => console.warn('  - ' + d));
+    } else {
+        console.log('Round-trip verified: recomposed payload is identical (0 information loss).');
+    }
+
+    // Register in the workspace for later pull/push — keyed by NAME, not id.
+    config.workspace = config.workspace || [];
+    const existing = config.workspace.findIndex(
+        (e) => e.object_type === 'long_running_process' && e.name === chosen.name
+    );
+    const entry = {
+        path: dest,
+        object_type: 'long_running_process',
+        name: chosen.name,
+        tenant_id: chosen.tenantId,
+        svg: chosen.bpmnFileSvg,
+        description,
+        // Baseline for push classification (see pull.js/push.js): checksum of
+        // the *recomposed* payload, changes only when local files change.
+        checksum_at_pull: computeChecksum(stableStringify(rebuilt)),
+        version: chosen.version,
+        status: chosen.status,
+    };
+    if (existing >= 0) config.workspace[existing] = entry;
+    else config.workspace.push(entry);
+    writeConfig(config);
+}
+
+export { cloneLrp };