envloop-cli 0.4.0__tar.gz → 1.7.0__tar.gz

{envloop_cli-0.4.0 → envloop_cli-1.7.0}/.gitignore

@@ -6,3 +6,6 @@ dist/
 
 # Local environment configuration is machine-specific and must not be committed.
 .env.local
+
+# Local runtime output from offline platform API contract fixtures.
+.envplatform/

envloop_cli-1.7.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: envloop-cli
+Version: 1.7.0
+Summary: EnvLoop CLI and Python SDK for jobs, training, checkpoints and inference
+Project-URL: Homepage, https://envloop.ai
+Project-URL: Documentation, https://docs.envloop.ai
+Project-URL: Repository, https://github.com/EnvLoop/envloop-cli
+Project-URL: Issues, https://github.com/EnvLoop/envloop-cli/issues
+Project-URL: Agent instructions, https://docs.envloop.ai/skill.md
+Requires-Python: >=3.11
+Requires-Dist: tinker==0.34.0
+Description-Content-Type: text/markdown
+
+# envloop-cli: EnvLoop CLI and Python SDK
+
+Install the public client to run agent Jobs, inspect Trials, manage training and
+checkpoints, and deploy or call inference endpoints. The `el` and `envloop`
+commands are equivalent. The Python import package is `envloop`.
+
+## Version 1.7
+
+- Use published Runner resource shortcuts for Train Jobs and fixed Checkpoint inputs for Inference Jobs.
+- Pass `--json` explicitly to `job submit`; failures retain safe error codes and recovery guidance.
+- Submit training through Train Jobs. The retired interactive `envloop.training` interface is removed.
+
+After upgrading, check `el --version` and `el job submit --help`. Execution also
+requires a matching platform, project permissions and published Runners; package
+installation alone does not establish those prerequisites. See the
+[PyPI release history](https://pypi.org/project/envloop-cli/#history) for published versions.
+
+## Install
+
+Use a Python virtual environment:
+
+```bash
+python -m pip install --upgrade envloop-cli
+el --help
+```
+
+The standard installation includes the client dependencies for managed training.
+Check that the SDK can be imported:
+
+```bash
+python -c 'from envloop import Client; print("EnvLoop SDK ready")'
+```
+
+When you see `EnvLoop SDK ready`, continue to Connect. This check imports the
+client without creating a Job. Submit training through `client.training_jobs`;
+follow the [managed training guide](https://docs.envloop.ai/training/cli-hello-world).
+
+Install the client in your Python environment; the platform provides the execution resources.
+
+## Connect
+
+Use an authorized EnvLoop account and project. Browser authorization:
+
+```bash
+el auth login
+el auth status --check
+```
+
+For an existing project API key, use the masked configuration wizard:
+
+```bash
+el auth config
+el auth status --check
+```
+
+CI can read credentials from `ENVLOOP_API_KEY` and connection settings from
+`ENVLOOP_BASE_URL`, `ENVLOOP_WORKSPACE_ID` and `ENVLOOP_PROJECT_ID`. Keep keys in
+your secret manager. Public API access is scoped to the authorized project.
+
+Credentials and settings live in `~/.envloop` (override with an absolute
+`ENVLOOP_HOME`). On POSIX the directory must be private and owned by you. Use the
+default path when the optional environment variable is unset:
+
+```bash
+mkdir -p "${ENVLOOP_HOME:-$HOME/.envloop}"
+chmod 700 "${ENVLOOP_HOME:-$HOME/.envloop}"
+```
+
+An insecure directory causes `el` to fail with `CONFIG_INSECURE_PATH`.
+
+## Explore your project
+
+```bash
+el job list --limit 5
+el job list --type train --limit 5
+el trail list --limit 5
+el trail list --type train --job-id JOB_ID
+el checkpoint list --limit 5
+el job list --type inference
+```
+
+Query a returned Job ID with `el job get JOB_ID` and `el job result JOB_ID`.
+Trial commands use the spelling `trail`, for example
+`el trail artifact list TRIAL_ID`. Use each command's `--help` for options.
+
+For the Python SDK:
+
+```python
+from envloop import Client
+
+with Client.remote() as client:
+    print(client.jobs.list(limit=5))
+    print(client.trials.list(type="train", limit=5))
+```
+
+Submitting work, training a model or starting inference can allocate billable
+resources. Follow the task-specific guide and retain the outputs you need before
+cleaning up temporary resources.
+
+## Sandbox jobs
+
+With a matching platform and a published `envhub/base` ANS Runner, submit a
+Sandbox Job without a Dataset:
+
+```bash
+el job submit --type sandbox --runner base --command 'python --version'
+el job submit --type sandbox --runner base --image python:3.11 --wait
+el job list --type sandbox
+el job log JOB_ID --follow
+```
+
+The platform resolves `base` to the registered `envhub/base@main` source ref and
+freezes its immutable Revision. The Sandbox image defaults to `python:3.11`;
+`--image` accepts an image name, tag or digest. The execution provider is configured
+by the server. Job logs retain the actual captured output and collection metadata.
+Failures include a code, readable explanation, HTTP status when available, and
+recovery guidance without echoing arbitrary response bodies or credentials.
+
+## Existing installations
+
+This distribution provides both the CLI and the `envloop` import package. Use a
+fresh environment if you previously installed the separate source distribution
+named `envloop`, so two distributions do not own the same Python module files.
+Existing client configuration is reused; installing a package does not change
+your account permissions or move remote resources. Check `el --help` when
+upgrading because command groups may differ from your earlier installation.
+
+## Documentation
+
+- [English documentation](https://docs.envloop.ai/)
+- [中文文档](https://docs.envloop.ai/zh-cn/)
+- [Installation](https://docs.envloop.ai/cli-install)
+- [CLI reference](https://docs.envloop.ai/reference/cli)
+- [Training and deployment](https://docs.envloop.ai/training/train-deploy)
+- [Agent entry: skill.md](https://docs.envloop.ai/skill.md)
+
+## Submit managed training
+
+Prepare a recipe-supported `REQUEST.json` using the [SFT quickstart](https://docs.envloop.ai/training/quickstart).
+Training uses billable resources. Check your project permissions, balance and data format, then submit once:
+
+```bash
+el job submit --type train --file REQUEST.json
+el job get JOB_ID
+el job log JOB_ID --follow
+el job result JOB_ID
+el checkpoint list --job-id JOB_ID
+```
+
+Replace `JOB_ID` with the receipt's value. Read the training status and logs, then find the registered checkpoint after success.
+Ctrl-C ends log reading; to stop training, use `el job stop JOB_ID` and check its state and resource cleanup.
+See [Checkpoints](https://docs.envloop.ai/training/checkpoints) to download or delete saved weights.
+
+The built-in SFT recipe does not support custom loss, RL or optimizer-state resume.
+For an older interactive training script, follow the [managed training migration](https://docs.envloop.ai/training/sdk-compatibility).
+
+## Run a GPU Runner
+
+Choose a published Runner readable in your project. Save this request as `gpu-run.json`, replacing `FULL_COMMIT` with the full Revision from `el runner list --json`:
+
+```json
+{
+  "request_id": "gpu-run-001",
+  "trials": [
+    {"name": "first", "spec": {"runner": "envhub/bash-runner@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 600}},
+    {"name": "second", "spec": {"runner": "envhub/bash-runner@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 600}}
+  ]
+}
+```
+
+```bash
+el job submit --type train --file gpu-run.json
+el job get JOB_ID
+el job log JOB_ID --follow
+el job result JOB_ID
+```
+
+Replace `JOB_ID` with the returned value. The example has two independent Trials, each requesting four H100 GPUs: concurrent execution needs eight GPUs. Capacity and budget determine actual concurrency. Startup and execution are billable; check the Runner requirements, project `training.run` permission and [training prices](https://docs.envloop.ai/pricing) first. Reduce the Trial or GPU count when your program supports a smaller first run.
+
+The request file does not depend on GPU shortcut flags. If `el job submit --help` lists both `--trails` and `--gput-type`, you can instead use the shortcuts in [GPU Runner training](https://docs.envloop.ai/training/runner). Choose one submission method to avoid duplicate runs. The SDK accepts the same dictionary through `client.training_jobs.submit(request)`.
+
+The platform starts the published Revision’s `main.sh` / `main.py` using the Runner image; it does not upload local code. An optional command can only supply a declared `run_command` parameter. If this mode or GPU type is unavailable, contact your project administrator. Use `el job stop JOB_ID` to stop every Trial, then inspect each Trial’s `cleanup_confirmed` and download the uploaded artifacts you need.

envloop_cli-1.7.0/README.pypi.md

@@ -0,0 +1,182 @@
+# envloop-cli: EnvLoop CLI and Python SDK
+
+Install the public client to run agent Jobs, inspect Trials, manage training and
+checkpoints, and deploy or call inference endpoints. The `el` and `envloop`
+commands are equivalent. The Python import package is `envloop`.
+
+## Version 1.7
+
+- Use published Runner resource shortcuts for Train Jobs and fixed Checkpoint inputs for Inference Jobs.
+- Pass `--json` explicitly to `job submit`; failures retain safe error codes and recovery guidance.
+- Submit training through Train Jobs. The retired interactive `envloop.training` interface is removed.
+
+After upgrading, check `el --version` and `el job submit --help`. Execution also
+requires a matching platform, project permissions and published Runners; package
+installation alone does not establish those prerequisites. See the
+[PyPI release history](https://pypi.org/project/envloop-cli/#history) for published versions.
+
+## Install
+
+Use a Python virtual environment:
+
+```bash
+python -m pip install --upgrade envloop-cli
+el --help
+```
+
+The standard installation includes the client dependencies for managed training.
+Check that the SDK can be imported:
+
+```bash
+python -c 'from envloop import Client; print("EnvLoop SDK ready")'
+```
+
+When you see `EnvLoop SDK ready`, continue to Connect. This check imports the
+client without creating a Job. Submit training through `client.training_jobs`;
+follow the [managed training guide](https://docs.envloop.ai/training/cli-hello-world).
+
+Install the client in your Python environment; the platform provides the execution resources.
+
+## Connect
+
+Use an authorized EnvLoop account and project. Browser authorization:
+
+```bash
+el auth login
+el auth status --check
+```
+
+For an existing project API key, use the masked configuration wizard:
+
+```bash
+el auth config
+el auth status --check
+```
+
+CI can read credentials from `ENVLOOP_API_KEY` and connection settings from
+`ENVLOOP_BASE_URL`, `ENVLOOP_WORKSPACE_ID` and `ENVLOOP_PROJECT_ID`. Keep keys in
+your secret manager. Public API access is scoped to the authorized project.
+
+Credentials and settings live in `~/.envloop` (override with an absolute
+`ENVLOOP_HOME`). On POSIX the directory must be private and owned by you. Use the
+default path when the optional environment variable is unset:
+
+```bash
+mkdir -p "${ENVLOOP_HOME:-$HOME/.envloop}"
+chmod 700 "${ENVLOOP_HOME:-$HOME/.envloop}"
+```
+
+An insecure directory causes `el` to fail with `CONFIG_INSECURE_PATH`.
+
+## Explore your project
+
+```bash
+el job list --limit 5
+el job list --type train --limit 5
+el trail list --limit 5
+el trail list --type train --job-id JOB_ID
+el checkpoint list --limit 5
+el job list --type inference
+```
+
+Query a returned Job ID with `el job get JOB_ID` and `el job result JOB_ID`.
+Trial commands use the spelling `trail`, for example
+`el trail artifact list TRIAL_ID`. Use each command's `--help` for options.
+
+For the Python SDK:
+
+```python
+from envloop import Client
+
+with Client.remote() as client:
+    print(client.jobs.list(limit=5))
+    print(client.trials.list(type="train", limit=5))
+```
+
+Submitting work, training a model or starting inference can allocate billable
+resources. Follow the task-specific guide and retain the outputs you need before
+cleaning up temporary resources.
+
+## Sandbox jobs
+
+With a matching platform and a published `envhub/base` ANS Runner, submit a
+Sandbox Job without a Dataset:
+
+```bash
+el job submit --type sandbox --runner base --command 'python --version'
+el job submit --type sandbox --runner base --image python:3.11 --wait
+el job list --type sandbox
+el job log JOB_ID --follow
+```
+
+The platform resolves `base` to the registered `envhub/base@main` source ref and
+freezes its immutable Revision. The Sandbox image defaults to `python:3.11`;
+`--image` accepts an image name, tag or digest. The execution provider is configured
+by the server. Job logs retain the actual captured output and collection metadata.
+Failures include a code, readable explanation, HTTP status when available, and
+recovery guidance without echoing arbitrary response bodies or credentials.
+
+## Existing installations
+
+This distribution provides both the CLI and the `envloop` import package. Use a
+fresh environment if you previously installed the separate source distribution
+named `envloop`, so two distributions do not own the same Python module files.
+Existing client configuration is reused; installing a package does not change
+your account permissions or move remote resources. Check `el --help` when
+upgrading because command groups may differ from your earlier installation.
+
+## Documentation
+
+- [English documentation](https://docs.envloop.ai/)
+- [中文文档](https://docs.envloop.ai/zh-cn/)
+- [Installation](https://docs.envloop.ai/cli-install)
+- [CLI reference](https://docs.envloop.ai/reference/cli)
+- [Training and deployment](https://docs.envloop.ai/training/train-deploy)
+- [Agent entry: skill.md](https://docs.envloop.ai/skill.md)
+
+## Submit managed training
+
+Prepare a recipe-supported `REQUEST.json` using the [SFT quickstart](https://docs.envloop.ai/training/quickstart).
+Training uses billable resources. Check your project permissions, balance and data format, then submit once:
+
+```bash
+el job submit --type train --file REQUEST.json
+el job get JOB_ID
+el job log JOB_ID --follow
+el job result JOB_ID
+el checkpoint list --job-id JOB_ID
+```
+
+Replace `JOB_ID` with the receipt's value. Read the training status and logs, then find the registered checkpoint after success.
+Ctrl-C ends log reading; to stop training, use `el job stop JOB_ID` and check its state and resource cleanup.
+See [Checkpoints](https://docs.envloop.ai/training/checkpoints) to download or delete saved weights.
+
+The built-in SFT recipe does not support custom loss, RL or optimizer-state resume.
+For an older interactive training script, follow the [managed training migration](https://docs.envloop.ai/training/sdk-compatibility).
+
+## Run a GPU Runner
+
+Choose a published Runner readable in your project. Save this request as `gpu-run.json`, replacing `FULL_COMMIT` with the full Revision from `el runner list --json`:
+
+```json
+{
+  "request_id": "gpu-run-001",
+  "trials": [
+    {"name": "first", "spec": {"runner": "envhub/bash-runner@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 600}},
+    {"name": "second", "spec": {"runner": "envhub/bash-runner@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 600}}
+  ]
+}
+```
+
+```bash
+el job submit --type train --file gpu-run.json
+el job get JOB_ID
+el job log JOB_ID --follow
+el job result JOB_ID
+```
+
+Replace `JOB_ID` with the returned value. The example has two independent Trials, each requesting four H100 GPUs: concurrent execution needs eight GPUs. Capacity and budget determine actual concurrency. Startup and execution are billable; check the Runner requirements, project `training.run` permission and [training prices](https://docs.envloop.ai/pricing) first. Reduce the Trial or GPU count when your program supports a smaller first run.
+
+The request file does not depend on GPU shortcut flags. If `el job submit --help` lists both `--trails` and `--gput-type`, you can instead use the shortcuts in [GPU Runner training](https://docs.envloop.ai/training/runner). Choose one submission method to avoid duplicate runs. The SDK accepts the same dictionary through `client.training_jobs.submit(request)`.
+
+The platform starts the published Revision’s `main.sh` / `main.py` using the Runner image; it does not upload local code. An optional command can only supply a declared `run_command` parameter. If this mode or GPU type is unavailable, contact your project administrator. Use `el job stop JOB_ID` to stop every Trial, then inspect each Trial’s `cleanup_confirmed` and download the uploaded artifacts you need.

{envloop_cli-0.4.0 → envloop_cli-1.7.0}/envloop/agent_runs.py

@@ -7,6 +7,7 @@ using the same rules as the Console's agent runs page.
 """
 
 from datetime import datetime
+from urllib.parse import quote, urlencode
 
 from .train import TrainJobs
 
@@ -206,3 +207,38 @@ class AgentRuns:
         if run not in runs:
             raise AgentRunError("AGENT_RUN_NOT_FOUND")
         return {**_detail(run, runs[run]), "observed_at": observed_at}
+
+    # The RSI loop service behind the platform (``/v1/agent-runs/rsi``). Starting spends money, so
+    # ``start`` needs a key with ``training.run``; ``control(stop)`` also needs ``training.stop``.
+    def _rsi(self, method: str, path: str, body=None) -> dict:
+        return self._train_jobs.transport.request(method, "/v1/agent-runs/rsi" + path, body)
+
+    def start(self, run: str, brief: str, *, model_usd_cap: float, usd_cap: float | None = None,
+              model_request_cap: int | None = None, domain: str | None = None, rounds: int | None = None,
+              dry_run: bool = False, student_model: str | None = None) -> dict:
+        """Start a new RSI run; the platform validates every field. ``dry_run`` uses no GPU."""
+        limits = {"model_usd_cap": model_usd_cap}
+        for key, value in (("usd_cap", usd_cap), ("model_request_cap", model_request_cap)):
+            if value is not None:
+                limits[key] = value
+        body = {"run": run, "brief": brief, "limits": limits}
+        for key, value in (("domain", domain), ("rounds", rounds), ("student_model", student_model)):
+            if value is not None:
+                body[key] = value
+        if dry_run:
+            body["dry_run"] = True
+        return self._rsi("POST", "/runs", body)
+
+    def live(self, run: str, since: int | None = None) -> dict:
+        """What a run does now; pass the previous ``next_cursor`` as ``since`` for newer events."""
+        query = "?" + urlencode({"since": since}) if since is not None else ""
+        return self._rsi("GET", f"/runs/{quote(run, safe='')}/live{query}")
+
+    def steer(self, run: str, text: str) -> dict:
+        """Queue a message for the running operator (1 to 4000 characters)."""
+        return self._rsi("POST", f"/runs/{quote(run, safe='')}/steer", {"text": text})
+
+    def control(self, run: str, action: str, rounds: int | None = None) -> dict:
+        """``extend`` (needs ``rounds``), ``stop`` (after the current round) or ``resume``."""
+        return self._rsi("POST", f"/runs/{quote(run, safe='')}/control",
+                         {"action": action, **({} if rounds is None else {"rounds": rounds})})

{envloop_cli-0.4.0 → envloop_cli-1.7.0}/envloop/cli.py

@@ -133,11 +133,11 @@ def log_page_size(value):
 
 def runner_arguments(submit):
     submit.add_argument("--runner", metavar="NAME[@REVISION]",
-                        help="Agent: override the Dataset runner with NAME@REVISION; Sandbox: registered Runner name (for example base)")
+                        help="Agent/Train: namespace/name@REVISION; Sandbox: registered Runner name (for example base)")
     submit.add_argument("--job-id", help="caller-selected Job ID")
     submit.add_argument("--tag", help="run label")
     submit.add_argument("--priority", type=int, help="waiting priority; larger values run first (default: 0)")
-    submit.add_argument("--command", help="shell script override executed in the runner directory; preserves multiline text")
+    submit.add_argument("--command", help="Agent/Sandbox: shell override; Train: declared run_command parameter passed to the published Runner entrypoint; preserves multiline text")
 
 
 def parser():
@@ -153,10 +153,20 @@ def parser():
     from .auth_cli import add_auth_commands
 
     jobs = groups.add_parser("job", help="Submit and manage Agent, Sandbox, Train and Inference Jobs").add_subparsers(dest="action", required=True)
-    job_submit = jobs.add_parser("submit", help="Submit an Agent, Sandbox, Train or Inference Job")
+    job_submit = jobs.add_parser("submit", help="Submit an Agent, Sandbox, Train or Inference Job", allow_abbrev=False)
     job_submit.add_argument("--type", choices=("agent", "sandbox", "train", "inference"), default="agent", help="Job type (default: agent)")
-    job_submit.add_argument("--image", metavar="IMAGE", help="Sandbox Docker image override (server default: python:3.11)")
-    job_submit.add_argument("--file", type=Path, help="Train or Inference Job request JSON (spec or Train trials array)")
+    job_submit.add_argument("--image", metavar="IMAGE", help="Sandbox image override (server default: python:3.11); Train Runner: public spelling of --docker")
+    from .train_runner_cli import memory_mebibytes, positive_integer
+
+    job_submit.add_argument("--docker", metavar="IMAGE", help="Train Runner Docker image override; omitted uses the Runner declaration")
+    job_submit.add_argument("--trails", type=positive_integer, metavar="COUNT", help="Train Runner: 1–16 independent Trials (default: 1)")
+    job_submit.add_argument("--gput-type", metavar="MODEL", help="Train Runner: GPU model for each Trial (for example H100)")
+    job_submit.add_argument("--gpu", type=positive_integer, metavar="COUNT", help="Train Runner: positive GPU count per Trial")
+    job_submit.add_argument("--cpu", type=positive_integer, metavar="COUNT", help="Train Runner: positive CPU count per Trial")
+    for option in ('memory', 'disk', 'shm-size'):
+        job_submit.add_argument('--' + option, type=memory_mebibytes, metavar="SIZE",
+                                help="Train Runner: per-Trial size in Mi/Gi/Ti (for example 64Gi)")
+    job_submit.add_argument("--file", type=Path, help="Managed Train or Inference Job JSON (spec or Train trials array; interactive training is unsupported)")
     job_submit.add_argument("--source", type=Path, help="two-file directory for a single-task Job")
     job_submit.add_argument("--task-id", help="select one task within the dataset")
     job_submit.add_argument(
@@ -175,10 +185,11 @@ def parser():
                             help="named runtime Profile; omitted version requires an explicit default")
     job_submit.add_argument("--seed", type=int)
     job_submit.add_argument("--timeout-sec", type=wait_seconds,
-                            help="Agent/Sandbox execution timeout (whole seconds); Train wait timeout (default: 600)")
+                            help="Agent/Sandbox or Train Runner execution timeout (whole seconds); Train --file wait timeout (default: 600)")
     job_submit.add_argument("--delete-delay", type=nonnegative_seconds, metavar="SECONDS",
                             help="keep each sandbox (E2B or Fly) after completion for SECONDS (default: 0); cancellation/timeout delete immediately")
     job_submit.add_argument("--wait", action="store_true")
+    job_submit.add_argument("--json", action="store_true", help="Output the complete response as JSON (the default for submit; accepted for consistency with list commands)")
     for action in ("get", "stop", "result", "pause", "resume", "wake", "event"):
         command = jobs.add_parser(action)
         command.add_argument("job_id")
@@ -208,6 +219,27 @@ def parser():
     runs_get = runs.add_parser("get", help="Show a run's rounds, Train Jobs and checkpoints")
     runs_get.add_argument("run", metavar="RUN", help="run label: user_metadata.rsi_run or agent_run")
     runs_get.add_argument("--json", action="store_true", help="Output the complete run as JSON (default: tables)")
+    runs_start = runs.add_parser("start", help="Start a new RSI loop run (paid; needs training.run)")
+    runs_start.add_argument("run", metavar="RUN", help="new run id: lower-case letters, digits and dashes")
+    brief = runs_start.add_mutually_exclusive_group(required=True)
+    brief.add_argument("--brief", help="the goal of the run (up to 4000 characters)")
+    brief.add_argument("--brief-file", metavar="PATH", help="read the goal from a file, or - for standard input")
+    runs_start.add_argument("--model-usd-cap", type=float, required=True, help="strong-model spend cap in USD (the hard stop)")
+    runs_start.add_argument("--usd-cap", type=float, help="cap in USD for model plus GPU training together")
+    runs_start.add_argument("--model-request-cap", type=int, help="cap on model requests")
+    runs_start.add_argument("--domain", help="task family (default: the service's default; an unknown value is rejected)")
+    runs_start.add_argument("--rounds", type=int, help="target rounds (default: the service's default)")
+    runs_start.add_argument("--dry-run", action="store_true", help="GPU-free run: trains nothing; exercises the loop, spends model budget only")
+    runs_start.add_argument("--student-model", help="gateway student model of a dry run")
+    runs_live = runs.add_parser("live", help="Show what a run does now; --follow streams new events")
+    runs_live.add_argument("run", metavar="RUN")
+    runs_live.add_argument("--since", type=int, help="only events after this cursor (the previous next_cursor)")
+    runs_live.add_argument("--follow", action="store_true", help="poll and print new events until the run ends; Ctrl-C exits without stopping it")
+    runs_steer = runs.add_parser("steer", help="Message the running operator now (needs training.run)")
+    runs_steer.add_argument("run", metavar="RUN")
+    runs_steer.add_argument("text", metavar="TEXT", help="1 to 4000 characters")
+    runs_stop = runs.add_parser("stop", help="Stop a run after its current round (needs training.run and training.stop)")
+    runs_stop.add_argument("run", metavar="RUN")
     tasks = groups.add_parser("trail", help="Inspect and control existing trials").add_subparsers(dest="action", required=True)
     listing = tasks.add_parser("list", help="List Agent, Sandbox, Train and Inference worker Trials")
     listing.add_argument("--type", choices=("agent", "sandbox", "train", "inference"), help="Filter by Trial type")
@@ -230,11 +262,11 @@ def parser():
     download.add_argument("trial_id")
     download.add_argument("directory", type=Path)
     profiles = groups.add_parser("profile", help="Manage platform runtime profiles").add_subparsers(dest="action", required=True)
-    put = profiles.add_parser("create", help="Create an immutable Profile version from JSON")
+    put = profiles.add_parser("create", help="Create an immutable Profile version from TOML or JSON")
     put.add_argument("name")
     put.add_argument("version")
-    put.add_argument("--file", type=Path, required=True, help="ProfileSpec JSON file")
-    put.add_argument("--runner", metavar="RUNNER", help="Bind org/name@<full-commit> to this version")
+    put.add_argument("--file", type=Path, required=True, help="Profile TOML or JSON file")
+    put.add_argument("--runner", metavar="RUNNER", help="Bind a Runner revision to this version")
     secret_input = put.add_mutually_exclusive_group()
     secret_input.add_argument("--prompt-model-api-key", action="store_true", help="Read the model API key from a non-echoing prompt")
     secret_input.add_argument("--model-api-key-stdin", action="store_true", help="Read the model API key from one line of standard input")
@@ -242,11 +274,16 @@ def parser():
     update.add_argument("name")
     update.add_argument("version", help="New version; existing versions cannot be overwritten")
     update.add_argument("--from-version", help="Source version; omit to use the explicit default")
-    update.add_argument("--file", type=Path, required=True, help="JSON patch: merge literal params keys, replace supplied metadata; preserve omitted fields")
-    update.add_argument("--runner", metavar="RUNNER", help="Bind a Runner name@full-commit; omit to preserve the source binding")
+    update.add_argument("--file", type=Path, required=True, help="TOML or JSON patch: merge params keys, replace supplied metadata; preserve omitted fields")
+    update.add_argument("--runner", metavar="RUNNER", help="Bind a Runner revision; v1 requires a full commit; omit to preserve the source binding")
     update_secret = update.add_mutually_exclusive_group()
     update_secret.add_argument("--prompt-model-api-key", action="store_true", help="Read an encrypted model connection key from a non-echoing prompt")
     update_secret.add_argument("--model-api-key-stdin", action="store_true", help="Read an encrypted model connection key from one line of standard input")
+    fork = profiles.add_parser('fork', help='Fork an existing Profile into a new immutable identity')
+    fork.add_argument('source_name')
+    fork.add_argument('source_version')
+    fork.add_argument('name')
+    fork.add_argument('version')
     get = profiles.add_parser("get")
     get.add_argument("name")
     get.add_argument("--version")
@@ -368,16 +405,27 @@ def main(argv=None):
             print(format_error(exc, args=args, program=cli.prog), file=sys.stderr)
             return 1
     if args.group == "job" and args.action == "submit":
+        from .train_runner_cli import SHORTCUT_FIELDS, runner_request
+
+        runner_mode = args.type == 'train' and args.file is None
+        if not runner_mode and any(getattr(args, key) is not None for key in SHORTCUT_FIELDS):
+            cli.error('Train Runner shortcuts require --type train --runner and cannot be combined with --file')
         if args.type in {"train", "inference"}:
-            if args.file is None:
+            if args.file is None and not runner_mode:
                 cli.error(f"--type {args.type} requires --file REQUEST.json")
             if args.type == 'inference' and (args.wait or args.timeout_sec is not None):
                 cli.error('Inference is a continuous service; --wait and --timeout-sec do not apply')
             agent_fields = ("dataset", "dataset_option", "source", "task_id", "config", "split", "revision",
-                            "runner", "job_id", "tag", "priority", "command", "attempts", "request_id",
-                            "profile", "seed", "delete_delay", "image")
+                            "job_id", "tag", "priority", "attempts", "profile", "seed", "delete_delay")
+            if not runner_mode:
+                agent_fields += ('runner', 'command', 'request_id', 'image')
             if any(getattr(args, key) is not None for key in agent_fields):
-                cli.error(f"--type {args.type} accepts its request through --file; Agent submission options cannot be combined")
+                cli.error(f"--type {args.type} cannot be combined with Agent submission options or mixed --file/Runner input")
+            if runner_mode:
+                try:
+                    args.train_request = runner_request(args)
+                except ValueError as exc:
+                    cli.error(str(exc))
         elif args.type == 'sandbox':
             from .sandbox import sandbox_runner_selector, validate_image
 
@@ -406,7 +454,8 @@ def main(argv=None):
                     args.runner = runner_selector(args.runner)
                 except ValueError as exc:
                     cli.error(str(exc))
-            if sum(value is not None for value in (args.dataset, args.dataset_option, args.source)) != 1:
+            selections = sum(value is not None for value in (args.dataset, args.dataset_option, args.source))
+            if selections != 1 and not (selections == 0 and args.profile):
                 cli.error("provide exactly one positional dataset, --dataset or --source")
             args.dataset = args.dataset if args.dataset is not None else args.dataset_option
             if args.source is not None and any(getattr(args, key) is not None for key in ("runner", "task_id", "config", "split", "revision")):
@@ -430,7 +479,7 @@ def main(argv=None):
 
                     raw = args.file.read_bytes()
                     patch = read_profile_patch(raw)
-                    if args.runner is not None:
+                    if args.action == 'update' and args.runner is not None:
                         patch = with_runner(patch, args.runner)
                         raw = json.dumps(patch).encode('utf-8')
                     secrets = None
@@ -450,8 +499,10 @@ def main(argv=None):
                             patch=patch, from_version=args.from_version, secrets=secrets)
                     else:
                         result = client.profiles.import_spec(
-                            raw, name=args.name, version=args.version, secrets=secrets
+                            raw, name=args.name, version=args.version, secrets=secrets, runner=args.runner
                         )
+                elif args.action == 'fork':
+                    result = client.profiles.fork(args.source_name, args.source_version, name=args.name, version=args.version)
                 elif args.action == "get":
                     result = client.profiles.get(args.name, args.version)
                 elif args.action == "list":
@@ -477,14 +528,15 @@ def main(argv=None):
                     if args.type == 'inference':
                         result = client.jobs.submit_inference(json.loads(args.file.read_text(encoding='utf-8')))
                     elif args.type == "train":
-                        result = client.training_jobs.submit(json.loads(args.file.read_text(encoding="utf-8")))
+                        request = args.train_request if args.file is None else json.loads(args.file.read_text(encoding="utf-8"))
+                        result = client.training_jobs.submit(request)
                     else:
                         result = client.jobs.submit(args.dataset, type=args.type, source=args.source, task_id=args.task_id,
                                                     attempts=args.attempts if args.attempts is not None else 1,
                                                     request_id=args.request_id, config=args.config, split=args.split,
                                                     revision=args.revision, **submission_options(args))
                     if args.wait:
-                        wait_options = {"timeout": args.timeout_sec} if args.type == "train" and args.timeout_sec is not None else {}
+                        wait_options = {"timeout": args.timeout_sec} if args.type == "train" and args.file is not None and args.timeout_sec is not None else {}
                         result = client.jobs.wait(result["job_id"], **wait_options)
                 elif args.action == 'event':
                     result = client.jobs.events(args.job_id)
@@ -495,6 +547,12 @@ def main(argv=None):
                     from .train_log_cli import read_logs
 
                     return read_logs(client.jobs, args)
+                elif args.action == "run" and args.run_action in {"start", "live", "steer", "stop"}:
+                    from .rsi_cli import run_rsi
+
+                    result = run_rsi(client.agent_runs, args)
+                    if result is None:
+                        return 0
                 elif args.action == "run":
                     result = client.agent_runs.list() if args.run_action == "list" else client.agent_runs.get(args.run)
                 elif args.action == "list":