vortex-cli 8.1.1__tar.gz → 8.2.0__tar.gz

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 8.1.1
+Version: 8.2.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -106,6 +106,18 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 8.2
+
+- **`object run` runs ACTIONs, and waits.** It calls the gateway's new `POST run` (gateway
+  `AppVersion` 0.1.4 or later) instead of sending `tell agenda run` to the console, and
+  reports how long the action took, its reply and any exception (see
+  [Running an action](#running-an-action)). An older gateway refuses it with `NOT_EXPOSED`.
+  It no longer accepts a SCHEDULED_ACTION.
+- **`vortex agenda`** lists the scheduled actions AGENDA has loaded and queues one with
+  `agenda run`, refusing the cases where AGENDA would silently do nothing (see
+  [The agenda](#the-agenda)). It replaces both `object run` on a scheduled action and
+  `vortex execute tell agenda run ...`.
+
 ## Upgrading to 8.1
 
 8.1 does two things. It replaces `vortex config` with plain top-level commands that read
@@ -289,7 +301,7 @@ vortex object list   [QUERY] [--app-id ID [--local]] [--strict --inherits-from|-
                      --ids-only --show-params --type T...] [--json]
 vortex object grep   PATTERN [--app-id ID] [--output-paths|--output-apps]
                      [--include-resources|--type T...] [--json]
-vortex object run    ID --app-id ID
+vortex object run    ID --app-id ID [--output] [--json]
 vortex object delete ID... --app-id ID [--yes]
 
 ── keyword ──────────────────────────────────────────────────────────────────
@@ -315,6 +327,10 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
                         --cascade-delete|--no-cascade-delete]
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
+── agenda ───────────────────────────────────────────────────────────────────
+vortex agenda [list] [--app-id ID] [--json]
+vortex agenda run    ID --app-id ID [--param KEY=VALUE ...] [--refresh --force] [--json]
+
 ── Workspace ────────────────────────────────────────────────────────────────
 vortex ls        [app list filters] [--json]      = app list --local
 vortex clone     APP... [--group --reclone --all --get-resources --open-urls --timeout]
@@ -412,7 +428,7 @@ addins match:
 
 | Shortcut | Sends | Effect |
 |---|---|---|
-| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run |
+| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run (raw text; `vortex agenda` parses it) |
 | `refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
 | `refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` | rebuilds the application's design from its template, as `app refresh` does (a clone is then out of date) |
 | `flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
@@ -420,12 +436,28 @@ addins match:
 `tell http flush cache` is **not** a valid command: the HTTP addin only matches
 `cache flush`, and anything else does nothing, silently. Use `flush-cache`.
 
-Two console operations act on one application or object, so they also live with those nouns:
-
-| Command | Sends |
-|---|---|
-| `vortex app refresh APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` - rebuilds the design from its template (a clone is then out of date) |
-| `vortex object run ID --app-id N` | `tell agenda run /group/app.pma/name` - runs an ACTION or SCHEDULED_ACTION now |
+`vortex app refresh APP_ID` also lives with its noun: it sends
+`tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N`, which rebuilds the design from its
+template (a clone is then out of date).
+
+### Running an action
+
+`vortex object run ID --app-id N` runs an ACTION now, as your identity, and waits for it:
+the gateway's `POST run` (`GatewaySystem`) loads the action's class, executes it and replies
+with how long it took, its redirect, content type and reply size. `--output` also prints the
+action's reply (its buffer, as text). An action that throws exits 1 with `ACTION_FAILED` and
+the exception; a path with no compiled ACTION is `NOT_FOUND`.
+
+- **ACTIONs only.** A SCHEDULED_ACTION (or any other type) is `WRONG_TYPE`. Scheduled
+  actions are queued with AGENDA: `vortex agenda run ID --app-id N` ([The agenda](#the-agenda)).
+- **No client connection.** The action's `getOutputStream()` is null, as under AGENDA, so it
+  must buffer its reply (`write`/`setBuffer`); one that streams unconditionally fails with
+  the NullPointerException as its result.
+- **Synchronous.** The CLI waits up to 300 s. Behind Cloudflare (prod) the request is cut
+  at about 100 s; the action still finishes on the server - check `vortex log`.
+- **Gateway required.** It needs a gateway with the `run` route; an older gateway refuses with
+  `NOT_EXPOSED`. Earlier versions of `object run` sent `tell agenda run`, which only reached
+  scheduled actions on AGENDA's list and did nothing, silently, for an ACTION.
 
 The 8.0 flags (`--show-schedule`, `--refresh-agenda`, `--flush-cache`, `--refresh-design`,
 `--run`) were removed in 8.1. `app refresh` was `app refresh-design` in 8.1.0; the old
@@ -573,6 +605,40 @@ vortex object get 7901 --app-id 62                     # the parsed schedule
   starts; if that lands between the command's read and write, the old `LastRun` is written
   back and the action may run one interval early.
 
+### The agenda
+
+AGENDA has no API beyond its console commands, so `vortex agenda` sends them through the same
+console route as `vortex execute` (the gateway's `POST console`, `GatewaySystem`, or the SOAP
+console without the gateway) and parses the text they answer.
+
+```
+vortex agenda -s dev                     # = agenda list
+vortex agenda list --app-id 9 -s dev
+vortex agenda run 7825 --app-id 60 -s dev [--param AppID=12] [--refresh] [--force]
+```
+
+- **`list`** - `tell agenda schedule`: every scheduled action AGENDA has **loaded**, by next
+  run (server time), with the waitlist and AGENDA's counts (running, waitlisted, scheduled,
+  max at once). An action with empty `Options` is loaded as *on demand only*. Not listed: an
+  action with `Schedule=N`, one in a disabled application or an application with scheduled
+  actions disabled, and one created or renamed since AGENDA's last refresh (every 15
+  minutes). AGENDA says how many actions are running, never which.
+- **`run`** - queues a SCHEDULED_ACTION: `tell agenda run /group/app.pma/Name[?&KEY=VALUE...]`.
+  It runs as the system session when one of AGENDA's slots is free; its result is only in
+  `vortex log`. AGENDA answers that command with nothing, whatever it did, so `run` checks
+  first and sends nothing when AGENDA would not run it:
+  - `NOT_ON_AGENDA` - the action has `Schedule=N` (give it a schedule first), or it is not on
+    the loaded list. `--refresh` sends `tell agenda refresh` and checks again (for an action
+    created or renamed in the last 15 minutes).
+  - `ALREADY_QUEUED` - it is already waitlisted; AGENDA would skip it.
+  - `PREFIX_COLLISION` - AGENDA matches the path by prefix and queues it once per matching
+    item, so `.../SyncAll` would also match an item `.../Sync` and run twice. `--force` sends
+    it anyway.
+  - `WRONG_TYPE` - not a SCHEDULED_ACTION (an ACTION is run with `vortex object run`).
+- A queued run moves the action's next scheduled run (AGENDA resets it), and it can't be
+  stopped from here (`vortex execute tell agenda stop /group/app.pma/Name` asks the action to
+  quit; it has to check for that itself).
+
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/README.md

@@ -62,6 +62,18 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 8.2
+
+- **`object run` runs ACTIONs, and waits.** It calls the gateway's new `POST run` (gateway
+  `AppVersion` 0.1.4 or later) instead of sending `tell agenda run` to the console, and
+  reports how long the action took, its reply and any exception (see
+  [Running an action](#running-an-action)). An older gateway refuses it with `NOT_EXPOSED`.
+  It no longer accepts a SCHEDULED_ACTION.
+- **`vortex agenda`** lists the scheduled actions AGENDA has loaded and queues one with
+  `agenda run`, refusing the cases where AGENDA would silently do nothing (see
+  [The agenda](#the-agenda)). It replaces both `object run` on a scheduled action and
+  `vortex execute tell agenda run ...`.
+
 ## Upgrading to 8.1
 
 8.1 does two things. It replaces `vortex config` with plain top-level commands that read
@@ -245,7 +257,7 @@ vortex object list   [QUERY] [--app-id ID [--local]] [--strict --inherits-from|-
                      --ids-only --show-params --type T...] [--json]
 vortex object grep   PATTERN [--app-id ID] [--output-paths|--output-apps]
                      [--include-resources|--type T...] [--json]
-vortex object run    ID --app-id ID
+vortex object run    ID --app-id ID [--output] [--json]
 vortex object delete ID... --app-id ID [--yes]
 
 ── keyword ──────────────────────────────────────────────────────────────────
@@ -271,6 +283,10 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
                         --cascade-delete|--no-cascade-delete]
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
+── agenda ───────────────────────────────────────────────────────────────────
+vortex agenda [list] [--app-id ID] [--json]
+vortex agenda run    ID --app-id ID [--param KEY=VALUE ...] [--refresh --force] [--json]
+
 ── Workspace ────────────────────────────────────────────────────────────────
 vortex ls        [app list filters] [--json]      = app list --local
 vortex clone     APP... [--group --reclone --all --get-resources --open-urls --timeout]
@@ -368,7 +384,7 @@ addins match:
 
 | Shortcut | Sends | Effect |
 |---|---|---|
-| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run |
+| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run (raw text; `vortex agenda` parses it) |
 | `refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
 | `refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` | rebuilds the application's design from its template, as `app refresh` does (a clone is then out of date) |
 | `flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
@@ -376,12 +392,28 @@ addins match:
 `tell http flush cache` is **not** a valid command: the HTTP addin only matches
 `cache flush`, and anything else does nothing, silently. Use `flush-cache`.
 
-Two console operations act on one application or object, so they also live with those nouns:
-
-| Command | Sends |
-|---|---|
-| `vortex app refresh APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` - rebuilds the design from its template (a clone is then out of date) |
-| `vortex object run ID --app-id N` | `tell agenda run /group/app.pma/name` - runs an ACTION or SCHEDULED_ACTION now |
+`vortex app refresh APP_ID` also lives with its noun: it sends
+`tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N`, which rebuilds the design from its
+template (a clone is then out of date).
+
+### Running an action
+
+`vortex object run ID --app-id N` runs an ACTION now, as your identity, and waits for it:
+the gateway's `POST run` (`GatewaySystem`) loads the action's class, executes it and replies
+with how long it took, its redirect, content type and reply size. `--output` also prints the
+action's reply (its buffer, as text). An action that throws exits 1 with `ACTION_FAILED` and
+the exception; a path with no compiled ACTION is `NOT_FOUND`.
+
+- **ACTIONs only.** A SCHEDULED_ACTION (or any other type) is `WRONG_TYPE`. Scheduled
+  actions are queued with AGENDA: `vortex agenda run ID --app-id N` ([The agenda](#the-agenda)).
+- **No client connection.** The action's `getOutputStream()` is null, as under AGENDA, so it
+  must buffer its reply (`write`/`setBuffer`); one that streams unconditionally fails with
+  the NullPointerException as its result.
+- **Synchronous.** The CLI waits up to 300 s. Behind Cloudflare (prod) the request is cut
+  at about 100 s; the action still finishes on the server - check `vortex log`.
+- **Gateway required.** It needs a gateway with the `run` route; an older gateway refuses with
+  `NOT_EXPOSED`. Earlier versions of `object run` sent `tell agenda run`, which only reached
+  scheduled actions on AGENDA's list and did nothing, silently, for an ACTION.
 
 The 8.0 flags (`--show-schedule`, `--refresh-agenda`, `--flush-cache`, `--refresh-design`,
 `--run`) were removed in 8.1. `app refresh` was `app refresh-design` in 8.1.0; the old
@@ -529,6 +561,40 @@ vortex object get 7901 --app-id 62                     # the parsed schedule
   starts; if that lands between the command's read and write, the old `LastRun` is written
   back and the action may run one interval early.
 
+### The agenda
+
+AGENDA has no API beyond its console commands, so `vortex agenda` sends them through the same
+console route as `vortex execute` (the gateway's `POST console`, `GatewaySystem`, or the SOAP
+console without the gateway) and parses the text they answer.
+
+```
+vortex agenda -s dev                     # = agenda list
+vortex agenda list --app-id 9 -s dev
+vortex agenda run 7825 --app-id 60 -s dev [--param AppID=12] [--refresh] [--force]
+```
+
+- **`list`** - `tell agenda schedule`: every scheduled action AGENDA has **loaded**, by next
+  run (server time), with the waitlist and AGENDA's counts (running, waitlisted, scheduled,
+  max at once). An action with empty `Options` is loaded as *on demand only*. Not listed: an
+  action with `Schedule=N`, one in a disabled application or an application with scheduled
+  actions disabled, and one created or renamed since AGENDA's last refresh (every 15
+  minutes). AGENDA says how many actions are running, never which.
+- **`run`** - queues a SCHEDULED_ACTION: `tell agenda run /group/app.pma/Name[?&KEY=VALUE...]`.
+  It runs as the system session when one of AGENDA's slots is free; its result is only in
+  `vortex log`. AGENDA answers that command with nothing, whatever it did, so `run` checks
+  first and sends nothing when AGENDA would not run it:
+  - `NOT_ON_AGENDA` - the action has `Schedule=N` (give it a schedule first), or it is not on
+    the loaded list. `--refresh` sends `tell agenda refresh` and checks again (for an action
+    created or renamed in the last 15 minutes).
+  - `ALREADY_QUEUED` - it is already waitlisted; AGENDA would skip it.
+  - `PREFIX_COLLISION` - AGENDA matches the path by prefix and queues it once per matching
+    item, so `.../SyncAll` would also match an item `.../Sync` and run twice. `--force` sends
+    it anyway.
+  - `WRONG_TYPE` - not a SCHEDULED_ACTION (an ACTION is run with `vortex object run`).
+- A queued run moves the action's next scheduled run (AGENDA resets it), and it can't be
+  stopped from here (`vortex execute tell agenda stop /group/app.pma/Name` asks the action to
+  quit; it has to check for that itself).
+
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "8.1.1"
+version = "8.2.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }

vortex_cli-8.2.0/vortex/commands/agenda.py

@@ -0,0 +1,403 @@
+"""
+vortex agenda [list] | run - the server's scheduled actions, through AGENDA.
+
+AGENDA (puakma.addin.agenda) has no API beyond its console commands, so
+both verbs go through the console route 'vortex execute' uses (the
+gateway's POST console, GatewaySystem, or the SOAP console without the
+gateway) and parse AGENDA's text replies:
+
+    tell agenda schedule         one line per LOADED item, sorted by path:
+                                 '/grp/app.pma/Name  1D  NextRun=Fri 09.Oct.26 22:00:00'
+    tell agenda status           counts: running, waitlisted, scheduled, ...
+    tell agenda waitlist status  one line per queued item: '/grp/app.pma/Name Running=...'
+
+'list' shows only what AGENDA has loaded: an action in a disabled app,
+an app with scheduled actions disabled, or one created since the last
+refresh (every 15 minutes) is not on it. No console command says which
+actions are running - only how many.
+
+'run' sends 'tell agenda run /grp/app.pma/Name', which AGENDA matches
+against its loaded list and queues (AGENDA.forceRun). That command
+answers nothing either way, so 'run' checks first what AGENDA would do:
+
+- Not on the list: AGENDA ignores the command silently - NOT_ON_AGENDA
+  (--refresh rereads the list first). 'Schedule=N' in the Options is
+  never loaded; EMPTY Options load as an on-demand item.
+- Already waitlisted: AGENDA skips it - ALREADY_QUEUED.
+- AGENDA matches by PREFIX (sent path startsWith item path, case-
+  insensitive) and queues the sent path once per matching item, so
+  'SyncAll' also matches an item 'Sync' and runs twice - PREFIX_COLLISION
+  unless --force.
+
+A queued run executes as the system session when a slot is free; its
+result is only in the server log. ACTIONs are run with 'object run'.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import logging
+import re
+from typing import Any
+
+from vortex import cli
+from vortex import registry
+from vortex.commands import execute
+from vortex.models import DesignType
+from vortex.output import CommandError
+from vortex.output import render_table
+from vortex.output import text
+from vortex.registry import Command
+from vortex.registry import Context
+from vortex.registry import usage
+from vortex.webdesign import to_int
+
+logger = logging.getLogger("vortex")
+
+SCHEDULE_CMD = execute.AGENDA_SCHEDULE_CMD
+REFRESH_CMD = execute.AGENDA_REFRESH_CMD
+STATUS_CMD = "tell agenda status"
+WAITLIST_CMD = "tell agenda waitlist status"
+RUN_CMD = "tell agenda run %s"
+
+# AgendaItem.getSchedule(): path, interval + type letter, next run
+_SCHEDULE_LINE = re.compile(r"^(/\S+)\s+(\d+)([A-Z])\s+NextRun=(.+?)\s*$")
+# AgendaAction.toString(): path, Running=, LastRun=
+_WAITLIST_LINE = re.compile(r"^(/\S+)\s+Running=")
+_STATUS_LINE = re.compile(r"^([A-Za-z][A-Za-z ]+):\s*(\d+)\s*$")
+# AgendaItem's SimpleDateFormat for NextRun
+_NEXT_RUN_FORMAT = "%a %d.%b.%y %H:%M:%S"
+# AgendaItem.SCHED_* letters
+_UNITS = {
+    "S": "sec",
+    "I": "min",
+    "H": "hour",
+    "D": "day",
+    "W": "week",
+    "M": "month",
+    "Y": "year",
+}
+_PARAM = re.compile(r"^[A-Za-z0-9_.-]+=[A-Za-z0-9_.:-]*$")
+
+
+def _console(ctx: Context, command: str) -> str:
+    return execute.console_command(ctx.server, command) or ""
+
+
+def parse_schedule(reply: str) -> list[dict[str, Any]]:
+    """The items of a 'tell agenda schedule' reply (lines that don't parse are skipped)."""
+    items = []
+    for line in reply.splitlines():
+        m = _SCHEDULE_LINE.match(line.strip())
+        if m is None:
+            continue
+        path, interval, unit, next_run = m.groups()
+        app_path, _, name = path.rpartition("/")
+        app = app_path.lstrip("/").removesuffix(".pma")
+        items.append(
+            {
+                "path": path,
+                "app": app,
+                "name": name,
+                "interval": int(interval),
+                "unit": unit,
+                "every": _every(int(interval), unit),
+                "nextRun": _next_run(next_run),
+            }
+        )
+    return items
+
+
+def _every(interval: int, unit: str) -> str:
+    if unit == "N":
+        return "on demand"
+    word = _UNITS.get(unit)
+    if word is None:
+        return f"{interval}{unit}"
+    return f"{interval} {word}{'' if interval == 1 else 's'}"
+
+
+def _next_run(value: str) -> str | None:
+    """NextRun as ISO 8601 (server time), None when UnScheduled, else as sent."""
+    if value == "UnScheduled":
+        return None
+    try:
+        return datetime.datetime.strptime(value, _NEXT_RUN_FORMAT).isoformat()
+    except ValueError:
+        return value
+
+
+def parse_status(reply: str) -> dict[str, int]:
+    """The counts in a 'tell agenda status' reply, camelCase keys ('Actions running' -> running)."""
+    counts = {}
+    for line in reply.splitlines():
+        m = _STATUS_LINE.match(line.strip())
+        if m is None:
+            continue
+        words = m.group(1).lower().removeprefix("actions ").split()
+        key = words[0] + "".join(w.title() for w in words[1:])
+        counts[key] = int(m.group(2))
+    return counts
+
+
+def parse_waitlist(reply: str) -> list[str]:
+    """The paths in a 'tell agenda waitlist status' reply."""
+    paths = []
+    for line in reply.splitlines():
+        m = _WAITLIST_LINE.match(line.strip())
+        if m is not None:
+            paths.append(m.group(1))
+    return paths
+
+
+def _sort_key(item: dict[str, Any]) -> tuple[int, str, str]:
+    # scheduled first by next run, then on-demand items by path
+    next_run = item["nextRun"]
+    return (0, next_run, item["path"]) if next_run else (1, "", item["path"])
+
+
+# -- list ------------------------------------------------------------------
+
+
+def _list(ctx: Context, args: argparse.Namespace) -> dict[str, Any]:
+    items = parse_schedule(_console(ctx, SCHEDULE_CMD))
+    queued = {p.lower() for p in parse_waitlist(_console(ctx, WAITLIST_CMD))}
+    if args.app_id is not None:
+        from vortex.commands.app import find_app_row
+
+        app = find_app_row(ctx, args.app_id)
+        group = text(app.get("appgroup"))
+        want = f"{group + '/' if group else ''}{text(app.get('appname'))}".lower()
+        items = [i for i in items if i["app"].lower() == want]
+    for item in items:
+        item["waitlisted"] = item["path"].lower() in queued
+    return {
+        "status": parse_status(_console(ctx, STATUS_CMD)),
+        "items": sorted(items, key=_sort_key),
+    }
+
+
+def _render_list(ctx: Context, args: argparse.Namespace, data: Any) -> None:
+    rows = [
+        (
+            i["app"],
+            i["name"],
+            i["every"],
+            (i["nextRun"] or "on demand only").replace("T", " "),
+            "waitlisted" if i["waitlisted"] else "",
+        )
+        for i in data["items"]
+    ]
+    if rows:
+        render_table(
+            rows, ["App", "Action", "Every", "Next run (server time)", "Queue"]
+        )
+    else:
+        print("No scheduled actions on the agenda")
+    status = data["status"]
+    if status:
+        print(
+            f"\n{status.get('scheduled', len(rows))} scheduled · "
+            f"{status.get('running', 0)} running · "
+            f"{status.get('waitlisted', 0)} waitlisted · "
+            f"max {status.get('maxConcurrentActions', '?')} at once"
+        )
+
+
+def _configure_list(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--app-id",
+        metavar="ID",
+        type=cli.positive_id,
+        help="Only this application's scheduled actions",
+    )
+
+
+# -- run -------------------------------------------------------------------
+
+
+def _params(args: argparse.Namespace) -> str:
+    """'?&k=v&k2=v2' for --param, as 'app refresh' sends RefreshDesign?&AppID=N."""
+    for param in args.param:
+        if not _PARAM.match(param):
+            usage(
+                args,
+                f"--param '{param}' must be KEY=VALUE (letters, digits, '_', '.', "
+                "'-'; the value may also hold ':')",
+            )
+    return "?&" + "&".join(args.param) if args.param else ""
+
+
+def _run(ctx: Context, args: argparse.Namespace) -> dict[str, Any]:
+    from vortex.commands.app import find_app_row
+
+    query = _params(args)
+    app = find_app_row(ctx, args.app_id)
+    row = ctx.client.get_design(args.app_id, args.id)
+    name = text(row.get("name"))
+    design_type = to_int(row.get("designtype") or 0)
+    if design_type != DesignType.SCHEDULED_ACTION:
+        try:
+            type_name = DesignType(design_type).name
+        except ValueError:
+            type_name = text(row.get("designtype"))
+        raise CommandError(
+            f"[{args.id}] {name} is a {type_name}: only a SCHEDULED_ACTION runs "
+            "through AGENDA",
+            "WRONG_TYPE",
+            hint=(
+                f"run an ACTION with: vortex object run {args.id} --app-id "
+                f"{args.app_id}"
+                if design_type == DesignType.ACTION
+                else None
+            ),
+        )
+    group = text(app.get("appgroup"))
+    path = f"/{group + '/' if group else ''}{text(app.get('appname'))}.pma/{name}"
+    sent = path + query
+    if "schedule=n" in text(row.get("options")).lower():
+        # AGENDA.refreshActionList skips 'Schedule=N' outright (empty Options
+        # load as on-demand instead), so --refresh can't help
+        raise CommandError(
+            f"{path} has Schedule=N (never), so AGENDA does not load it and would "
+            "ignore the run (silently) - nothing was sent",
+            "NOT_ON_AGENDA",
+            hint=(
+                f"give it a schedule first: vortex object update {args.id} "
+                f"--app-id {args.app_id} --schedule D --start-time 03:00 ..."
+            ),
+        )
+
+    items = parse_schedule(_console(ctx, SCHEDULE_CMD))
+    refreshed = False
+    if args.refresh and not _on_agenda(items, path):
+        _console(ctx, REFRESH_CMD)
+        refreshed = True
+        items = parse_schedule(_console(ctx, SCHEDULE_CMD))
+    if not _on_agenda(items, path):
+        raise CommandError(
+            f"{path} is not on AGENDA's list, so AGENDA would ignore the run "
+            "(silently) - nothing was sent",
+            "NOT_ON_AGENDA",
+            hint=(
+                "the application or its scheduled actions are disabled"
+                if refreshed
+                else "if it was created or renamed in the last 15 minutes, pass "
+                "--refresh; otherwise the application or its scheduled actions "
+                "are disabled"
+            ),
+        )
+    if any(
+        p.lower() == path.lower() for p in parse_waitlist(_console(ctx, WAITLIST_CMD))
+    ):
+        raise CommandError(
+            f"{path} is already waitlisted - AGENDA would skip the run",
+            "ALREADY_QUEUED",
+        )
+    others = [
+        i["path"]
+        for i in items
+        if sent.lower().startswith(i["path"].lower())
+        and i["path"].lower() != path.lower()
+    ]
+    if others and not args.force:
+        raise CommandError(
+            f"AGENDA matches by prefix: {sent} also matches {', '.join(others)}, "
+            f"so it would queue {name} {len(others) + 1} times - nothing was sent",
+            "PREFIX_COLLISION",
+            hint="pass --force to send it anyway",
+        )
+
+    command = RUN_CMD % sent
+    _console(ctx, command)
+    return {
+        "designbucketid": row.get("designbucketid"),
+        "name": name,
+        "path": sent,
+        "command": command,
+        "agendaRefreshed": refreshed,
+        "queued": len(others) + 1,
+    }
+
+
+def _on_agenda(items: list[dict[str, Any]], path: str) -> bool:
+    return any(i["path"].lower() == path.lower() for i in items)
+
+
+def _render_run(ctx: Context, args: argparse.Namespace, data: Any) -> None:
+    times = f" {data['queued']} times" if data["queued"] > 1 else ""
+    print(
+        f"Queued {data['path']} with AGENDA{times}: it runs as the system session "
+        "when a slot is free.\nFollow it with: vortex agenda -s "
+        f"{ctx.server.name} / vortex log -s {ctx.server.name}"
+    )
+
+
+def _configure_run(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("id", metavar="ID", type=cli.positive_id)
+    parser.add_argument(
+        "--app-id",
+        metavar="ID",
+        type=cli.positive_id,
+        required=True,
+        help="The scheduled action's application (numeric)",
+    )
+    parser.add_argument(
+        "--param",
+        metavar="KEY=VALUE",
+        action="append",
+        default=[],
+        help="Pass a parameter to the action (repeatable): ...Name?&KEY=VALUE",
+    )
+    parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Reread AGENDA's list first when the action is not on it",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Send even when another action's path is a prefix of this one",
+    )
+
+
+COMMANDS = [
+    Command(
+        "agenda",
+        "list",
+        "The scheduled actions AGENDA has loaded, by next run",
+        _list,
+        routes=(registry.CONSOLE,),
+        configure=_configure_list,
+        render=_render_list,
+        note="--app-id also reads the inventory",
+        description=(
+            "The scheduled actions AGENDA has loaded ('tell agenda schedule'),\n"
+            "sorted by next run, with the waitlist and AGENDA's counts. Only\n"
+            "what AGENDA loaded: an action in a disabled app, in an app with\n"
+            "scheduled actions disabled, or created since the last refresh is\n"
+            "not listed. 'vortex agenda' alone is 'vortex agenda list'."
+        ),
+    ),
+    Command(
+        "agenda",
+        "run",
+        "Queue a scheduled action with AGENDA now",
+        _run,
+        routes=(registry.INVENTORY, registry.DESIGN_GET, registry.CONSOLE),
+        write=True,
+        configure=_configure_run,
+        render=_render_run,
+        description=(
+            "Queue a SCHEDULED_ACTION with AGENDA now ('tell agenda run\n"
+            "/group/app.pma/Name'). It runs as the system session when a slot\n"
+            "is free; its result is only in 'vortex log'. Checked first,\n"
+            "because AGENDA answers nothing: refused when the action is not on\n"
+            "AGENDA's list (NOT_ON_AGENDA; --refresh rereads it), already\n"
+            "waitlisted (ALREADY_QUEUED), or would also match another action\n"
+            "by prefix and run twice (PREFIX_COLLISION; --force sends it).\n"
+            "ACTIONs are run with 'vortex object run'."
+        ),
+    ),
+]

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex/commands/execute.py

@@ -17,7 +17,6 @@ from vortex.workspace import Workspace
 logger = logging.getLogger("vortex")
 
 REFRESH_APPLICATION_CMD = "tell agenda run /%s/RefreshDesign?&AppID=%d"
-RUN_CMD = "tell agenda run /%s"
 # The console shortcuts - the exact strings the addins match
 # (AGENDA.java tell(): "schedule", "refresh"; HTTP.java tell(): "cache flush"
 # only - 'tell http flush cache' silently does nothing)
@@ -56,11 +55,6 @@ def refresh_design_command(server: PuakmaServer, app_id: int) -> str:
     return REFRESH_APPLICATION_CMD % (server.webdesign_path, app_id)
 
 
-def run_command(server_path: str) -> str:
-    """'tell agenda run /group/app.pma/action' for a design's server path."""
-    return RUN_CMD % server_path.lstrip("/")
-
-
 def resolve_command(words: list[str]) -> str:
     """The console command for 'vortex execute WORDS...': a shortcut, or the words."""
     command = " ".join(words).strip()

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex/commands/object_.py

@@ -1073,49 +1073,80 @@ def _add_content(parser: argparse.ArgumentParser) -> None:
 
 # -- run -------------------------------------------------------------------
 
-_RUNNABLE = (DesignType.ACTION, DesignType.SCHEDULED_ACTION)
+_RUN_REFUSAL_HELP = {
+    "NOT_EXPOSED": (
+        "this server's gateway has no run route - upgrade vortex/gateway "
+        "(object run no longer goes through the console)"
+    ),
+    "NOT_FOUND": "the server has no compiled ACTION at that path",
+}
 
 
-def _run(ctx: Context, args: argparse.Namespace) -> dict[str, Any]:
-    from vortex.commands import execute
+def _run(ctx: Context, args: argparse.Namespace) -> dict[str, Any] | Outcome:
     from vortex.commands.app import find_app_row
+    from vortex.webdesign import GatewayClient
+    from vortex.webdesign import GatewayRefused
+    from vortex.webdesign import refusal_detail
 
     app = find_app_row(ctx, args.app_id)
     row = ctx.client.get_design(args.app_id, args.id)
-    try:
-        design_type = DesignType(to_int(row.get("designtype") or 0))
-    except ValueError:
-        design_type = DesignType.ERROR
     name = text(row.get("name"))
-    if design_type not in _RUNNABLE:
+    design_type = to_int(row.get("designtype") or 0)
+    if design_type != DesignType.ACTION:
+        hint = None
+        if design_type == DesignType.SCHEDULED_ACTION:
+            hint = (
+                "queue it with AGENDA: vortex agenda run "
+                f"{args.id} --app-id {args.app_id}"
+            )
         raise CommandError(
             f"[{args.id}] {name} is a {_type_name(row.get('designtype'))}: only "
-            "an ACTION or SCHEDULED_ACTION can be run",
+            "an ACTION can be run",
             "WRONG_TYPE",
+            hint=hint,
         )
     group = text(app.get("appgroup"))
-    server_path = f"{group + '/' if group else ''}{text(app.get('appname'))}.pma/{name}"
-    command = execute.run_command(server_path)
-    reply = execute.console_command(ctx.server, command)
-    return {
+    path = f"/{group + '/' if group else ''}{text(app.get('appname'))}.pma/{name}"
+    try:
+        with ctx.server as s:
+            reply = GatewayClient(s).run(path, reply=args.output)
+    except GatewayRefused as e:
+        raise CommandError(
+            refusal_detail(e, _RUN_REFUSAL_HELP), e.error_code, role=e.role
+        ) from e
+    data = {
         "designbucketid": row.get("designbucketid"),
         "name": name,
-        "designtype": row.get("designtype"),
-        "path": f"/{server_path}",
-        "command": command,
-        "reply": reply or "",
+        **{k: v for k, v in reply.items() if k != "ok"},
     }
+    if data.get("exception"):
+        return Outcome(
+            data,
+            CommandError(f"{path} threw: {data['exception']}", "ACTION_FAILED"),
+        )
+    return data
 
 
 def _render_run(ctx: Context, args: argparse.Namespace, data: Any) -> None:
-    print(f"Sent: {data['command']}")
-    if data["reply"]:
-        print(data["reply"])
+    seconds = to_int(data.get("durationMs") or 0) / 1000
+    if data.get("exception"):
+        print(f"Ran {data['path']}: it threw after {seconds:.2f}s")
+        return
+    print(f"Ran {data['path']} in {seconds:.2f}s")
+    if data.get("redirectTo"):
+        print(f"Redirect: {data['redirectTo']}")
+    if args.output and data.get("body"):
+        print(data["body"])
 
 
 def _configure_run(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("id", metavar="ID", type=cli.positive_id)
     _add_app_id(parser)
+    parser.add_argument(
+        "--output",
+        action="store_true",
+        help="Also print the action's reply (its buffer, as text)",
+    )
 
 
 def _configure_get(parser: argparse.ArgumentParser) -> None:
@@ -1245,17 +1276,18 @@ COMMANDS = [
     Command(
         "object",
         "run",
-        "Run an action or scheduled action now (AGENDA 'tell agenda run')",
+        "Run an action now and wait for it (the gateway's POST run)",
         _run,
-        routes=(registry.INVENTORY, registry.DESIGN_GET, registry.CONSOLE),
+        routes=(registry.INVENTORY, registry.DESIGN_GET, registry.RUN),
         write=True,
         configure=_configure_run,
         render=_render_run,
         description=(
-            "Run an ACTION or SCHEDULED_ACTION now: sends\n"
-            "'tell agenda run /group/app.pma/name' to the console (the gateway's\n"
-            "POST console needs GatewaySystem). Check 'vortex log' for what\n"
-            "the action did."
+            "Run an ACTION now, as this identity, and wait for it to finish:\n"
+            "the gateway's POST run (needs GatewaySystem) loads and executes\n"
+            "the action and reports how long it took, its redirect and reply\n"
+            "size - and the exception if it threw (exit 1). --output prints\n"
+            "the action's reply. Scheduled actions are not run here."
         ),
     ),
 ]

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex/main.py

@@ -84,6 +84,8 @@ STUBS = {
 REMOVED_IN = {"config": "8.1", "find": "8.1", "grep": "8.1", "libs": "8.1"}
 # Old names that still work, quietly: rewritten before parsing
 ALIASES = {"use": ["server", "use"], "ls": ["app", "list", "--local"]}
+# Nouns that run a verb when given none ('vortex agenda' = 'vortex agenda list')
+DEFAULT_VERBS = {"agenda": "list"}
 # 7.x forms of commands whose NAME 8.0 reuses as a noun
 OLD_FORMS = {
     "db": (
@@ -115,7 +117,14 @@ def _command_index(tokens: Sequence[str]) -> int | None:
 
 def _apply_aliases(argv: list[str]) -> list[str]:
     i = _command_index(argv)
-    if i is None or argv[i] not in ALIASES:
+    if i is None:
+        return argv
+    if argv[i] in DEFAULT_VERBS:
+        rest = argv[i + 1 :]
+        if not rest or (rest[0].startswith("-") and rest[0] not in ("-h", "--help")):
+            return [*argv[: i + 1], DEFAULT_VERBS[argv[i]], *rest]
+        return argv
+    if argv[i] not in ALIASES:
         return argv
     return [*argv[:i], *ALIASES[argv[i]], *argv[i + 1 :]]
 

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex/registry.py

@@ -70,6 +70,7 @@ SYSTEMJAR = "GET /systemjar"
 WHOAMI = "GET /whoami"
 LOGS = "GET /logs"
 CONSOLE = "POST /console"
+RUN = "POST /run"
 EXPORT = "GET /export"
 IMPORT = "POST /import"
 
@@ -78,6 +79,7 @@ NOUN_HELP = {
     "object": "Design objects: list, get, grep, create, update, diff, copy, delete, run",
     "keyword": "Application keywords: list, get, set, delete",
     "db": "Databases: connections, SQL queries and the data dictionary",
+    "agenda": "Scheduled actions (AGENDA): list, run",
 }
 
 
@@ -203,6 +205,7 @@ class Command:
 
 
 def all_commands() -> list[Command]:
+    from vortex.commands import agenda
     from vortex.commands import app
     from vortex.commands import db
     from vortex.commands import diff
@@ -219,6 +222,7 @@ def all_commands() -> list[Command]:
         *keyword.COMMANDS,
         *db.COMMANDS,
         *fetch.COMMANDS,
+        *agenda.COMMANDS,
     ]
 
 

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex/webdesign.py

@@ -24,10 +24,10 @@ webdesign's own. It adds three things:
 - Guards: no ids that belong to another application (NOT_FOUND), no
   system database (SYSTEM_DB), one DML/SELECT statement per SQL request
   (SQL_NOT_ALLOWED).
-- Its own routes on the same base URL: whoami, logs, console, export
-  and import (GatewayClient). Without the gateway, whoami/logs/console/
-  import do not exist (GatewayNotInstalled); export uses webdesign's
-  ExportPMX.
+- Its own routes on the same base URL: whoami, logs, console, run,
+  export and import (GatewayClient). Without the gateway, whoami/logs/
+  console/run/import do not exist (GatewayNotInstalled); export uses
+  webdesign's ExportPMX.
 
 Every failure carries a machine-readable code (`.code`): the gateway's
 own refusal code as sent, or one the CLI sets - NOT_FOUND (404),
@@ -110,6 +110,8 @@ _ZIP_MAGIC = b"PK\x03\x04"
 DOWNLOAD_TIMEOUT_SECONDS = 120
 UPDATE_TIMEOUT_SECONDS = 60
 REQUEST_TIMEOUT_SECONDS = 30
+# object run waits for the action to finish (prod's Cloudflare still cuts at ~100s)
+RUN_TIMEOUT_SECONDS = 300
 
 _ROUTE_MISSING = "Api does not exist"
 
@@ -775,7 +777,7 @@ class WhoAmI(NamedTuple):
 class GatewayClient(WebDesignClient):
     """
     The gateway's local routes (never forwarded to webdesign): whoami, logs,
-    console, export and import. On a server with a blank gateway_path they
+    console, run, export and import. On a server with a blank gateway_path they
     raise GatewayNotInstalled - except export, which goes to webdesign's
     ExportPMX instead.
     """
@@ -831,6 +833,19 @@ class GatewayClient(WebDesignClient):
         reply = _as_dict(self._request("POST", "console", {"cmd": cmd}))
         return str(reply.get("reply") or "")
 
+    def run(self, path: str, reply: bool = False) -> dict[str, Any]:
+        """
+        POST run (GatewaySystem): runs the ACTION at path
+        (/group/app.pma/Name) now, as this identity, and waits for it. The
+        reply is {ok, path, durationMs, redirectTo, contentType,
+        httpReplyCode, size}, plus body (the action's reply as text) when
+        reply is True, or exception when the action threw. A path that is
+        not a compiled ACTION is NOT_FOUND.
+        """
+        self._require_gateway("'vortex object run'")
+        body = {"path": path, "reply": "1" if reply else ""}
+        return _as_dict(self._request("POST", "run", body, timeout=RUN_TIMEOUT_SECONDS))
+
     def get_last_log_items(
         self,
         limit_items: int,

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 8.1.1
+Version: 8.2.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -106,6 +106,18 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 8.2
+
+- **`object run` runs ACTIONs, and waits.** It calls the gateway's new `POST run` (gateway
+  `AppVersion` 0.1.4 or later) instead of sending `tell agenda run` to the console, and
+  reports how long the action took, its reply and any exception (see
+  [Running an action](#running-an-action)). An older gateway refuses it with `NOT_EXPOSED`.
+  It no longer accepts a SCHEDULED_ACTION.
+- **`vortex agenda`** lists the scheduled actions AGENDA has loaded and queues one with
+  `agenda run`, refusing the cases where AGENDA would silently do nothing (see
+  [The agenda](#the-agenda)). It replaces both `object run` on a scheduled action and
+  `vortex execute tell agenda run ...`.
+
 ## Upgrading to 8.1
 
 8.1 does two things. It replaces `vortex config` with plain top-level commands that read
@@ -289,7 +301,7 @@ vortex object list   [QUERY] [--app-id ID [--local]] [--strict --inherits-from|-
                      --ids-only --show-params --type T...] [--json]
 vortex object grep   PATTERN [--app-id ID] [--output-paths|--output-apps]
                      [--include-resources|--type T...] [--json]
-vortex object run    ID --app-id ID
+vortex object run    ID --app-id ID [--output] [--json]
 vortex object delete ID... --app-id ID [--yes]
 
 ── keyword ──────────────────────────────────────────────────────────────────
@@ -315,6 +327,10 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
                         --cascade-delete|--no-cascade-delete]
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
+── agenda ───────────────────────────────────────────────────────────────────
+vortex agenda [list] [--app-id ID] [--json]
+vortex agenda run    ID --app-id ID [--param KEY=VALUE ...] [--refresh --force] [--json]
+
 ── Workspace ────────────────────────────────────────────────────────────────
 vortex ls        [app list filters] [--json]      = app list --local
 vortex clone     APP... [--group --reclone --all --get-resources --open-urls --timeout]
@@ -412,7 +428,7 @@ addins match:
 
 | Shortcut | Sends | Effect |
 |---|---|---|
-| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run |
+| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run (raw text; `vortex agenda` parses it) |
 | `refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
 | `refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` | rebuilds the application's design from its template, as `app refresh` does (a clone is then out of date) |
 | `flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
@@ -420,12 +436,28 @@ addins match:
 `tell http flush cache` is **not** a valid command: the HTTP addin only matches
 `cache flush`, and anything else does nothing, silently. Use `flush-cache`.
 
-Two console operations act on one application or object, so they also live with those nouns:
-
-| Command | Sends |
-|---|---|
-| `vortex app refresh APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` - rebuilds the design from its template (a clone is then out of date) |
-| `vortex object run ID --app-id N` | `tell agenda run /group/app.pma/name` - runs an ACTION or SCHEDULED_ACTION now |
+`vortex app refresh APP_ID` also lives with its noun: it sends
+`tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N`, which rebuilds the design from its
+template (a clone is then out of date).
+
+### Running an action
+
+`vortex object run ID --app-id N` runs an ACTION now, as your identity, and waits for it:
+the gateway's `POST run` (`GatewaySystem`) loads the action's class, executes it and replies
+with how long it took, its redirect, content type and reply size. `--output` also prints the
+action's reply (its buffer, as text). An action that throws exits 1 with `ACTION_FAILED` and
+the exception; a path with no compiled ACTION is `NOT_FOUND`.
+
+- **ACTIONs only.** A SCHEDULED_ACTION (or any other type) is `WRONG_TYPE`. Scheduled
+  actions are queued with AGENDA: `vortex agenda run ID --app-id N` ([The agenda](#the-agenda)).
+- **No client connection.** The action's `getOutputStream()` is null, as under AGENDA, so it
+  must buffer its reply (`write`/`setBuffer`); one that streams unconditionally fails with
+  the NullPointerException as its result.
+- **Synchronous.** The CLI waits up to 300 s. Behind Cloudflare (prod) the request is cut
+  at about 100 s; the action still finishes on the server - check `vortex log`.
+- **Gateway required.** It needs a gateway with the `run` route; an older gateway refuses with
+  `NOT_EXPOSED`. Earlier versions of `object run` sent `tell agenda run`, which only reached
+  scheduled actions on AGENDA's list and did nothing, silently, for an ACTION.
 
 The 8.0 flags (`--show-schedule`, `--refresh-agenda`, `--flush-cache`, `--refresh-design`,
 `--run`) were removed in 8.1. `app refresh` was `app refresh-design` in 8.1.0; the old
@@ -573,6 +605,40 @@ vortex object get 7901 --app-id 62                     # the parsed schedule
   starts; if that lands between the command's read and write, the old `LastRun` is written
   back and the action may run one interval early.
 
+### The agenda
+
+AGENDA has no API beyond its console commands, so `vortex agenda` sends them through the same
+console route as `vortex execute` (the gateway's `POST console`, `GatewaySystem`, or the SOAP
+console without the gateway) and parses the text they answer.
+
+```
+vortex agenda -s dev                     # = agenda list
+vortex agenda list --app-id 9 -s dev
+vortex agenda run 7825 --app-id 60 -s dev [--param AppID=12] [--refresh] [--force]
+```
+
+- **`list`** - `tell agenda schedule`: every scheduled action AGENDA has **loaded**, by next
+  run (server time), with the waitlist and AGENDA's counts (running, waitlisted, scheduled,
+  max at once). An action with empty `Options` is loaded as *on demand only*. Not listed: an
+  action with `Schedule=N`, one in a disabled application or an application with scheduled
+  actions disabled, and one created or renamed since AGENDA's last refresh (every 15
+  minutes). AGENDA says how many actions are running, never which.
+- **`run`** - queues a SCHEDULED_ACTION: `tell agenda run /group/app.pma/Name[?&KEY=VALUE...]`.
+  It runs as the system session when one of AGENDA's slots is free; its result is only in
+  `vortex log`. AGENDA answers that command with nothing, whatever it did, so `run` checks
+  first and sends nothing when AGENDA would not run it:
+  - `NOT_ON_AGENDA` - the action has `Schedule=N` (give it a schedule first), or it is not on
+    the loaded list. `--refresh` sends `tell agenda refresh` and checks again (for an action
+    created or renamed in the last 15 minutes).
+  - `ALREADY_QUEUED` - it is already waitlisted; AGENDA would skip it.
+  - `PREFIX_COLLISION` - AGENDA matches the path by prefix and queues it once per matching
+    item, so `.../SyncAll` would also match an item `.../Sync` and run twice. `--force` sends
+    it anyway.
+  - `WRONG_TYPE` - not a SCHEDULED_ACTION (an ACTION is run with `vortex object run`).
+- A queued run moves the action's next scheduled run (AGENDA resets it), and it can't be
+  stopped from here (`vortex execute tell agenda stop /group/app.pma/Name` asks the action to
+  quit; it has to check for that itself).
+
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in

{vortex_cli-8.1.1 → vortex_cli-8.2.0}/vortex_cli.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ vortex/util.py
 vortex/webdesign.py
 vortex/workspace.py
 vortex/commands/__init__.py
+vortex/commands/agenda.py
 vortex/commands/app.py
 vortex/commands/clean.py
 vortex/commands/clone.py