Add remyxai outrider trigger command (#42)

* Add `remyxai outrider trigger` command (REMYX-148)

A new subcommand that dispatches a one-shot Outrider run on a repo
via workflow_dispatch — useful for kicking off ad-hoc method-targeted
PRs without waiting for the next scheduled run.

  remyxai outrider trigger --repo owner/name \
    --pin-method "knowledge distillation"

Mirrors `outrider setup-local`: authenticates via the user's `gh` CLI,
no Remyx engine round-trip and no Remyx App requirement.

Pre-flight refuses to dispatch when the target repo doesn't have an
Outrider workflow registered. The check probes the Actions API (not
the Contents API) — the workflow file existing on disk isn't the
same as GitHub having indexed it for dispatch. Surfaces a clear hint
pointing at `remyxai outrider init` / `setup-local`.

Pairs with the new `pin-method` input on the Outrider action.
`--pin-method` and `--pin-arxiv` are mutually exclusive at both the
CLI layer (click usage error) and the handler.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Use `gh workflow run` to dispatch (nests inputs.* correctly)

The raw POST to /repos/{repo}/actions/workflows/{wf}/dispatches accepts
only `ref` and `inputs` at the top level; any extra top-level key is
rejected with HTTP 422 "X is not a permitted key". Passing
`-f pin-method=X` to `gh api` puts the key at the top level, not under
`inputs.*`, so even a workflow that correctly declares the input
rejects the call.

`gh workflow run` wraps the supplied `-f key=val` args under `inputs`
automatically — the right tool for this job.

Caught during the first end-to-end dogfood on smellslikeml/ag2:
the workflow declared the inputs and the action accepted them, but
GitHub rejected the dispatch before the action ever saw the request.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Document the discover → trigger workflow in docs/

Adds docs/method-targeted-runs.md covering: how to find arxiv ids via
`papers list` / `search query`, how to dispatch with `outrider trigger`,
both `--pin-method` shapes (arxiv id and free-text), the pre-flight
behavior, and how `--pin-method` differs from the legacy `--pin-arxiv`.

README gets a one-sentence pointer to the doc + command-reference
table additions for the new `outrider trigger` / `outrider setup-local`
/ `search query` commands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: smellslikeml

README.md

@@ -112,6 +112,10 @@ Set with `--mode` (default `auto`):
 - `auto` — provision, merge the setup PR, and start the first run
 - `review` — provision and open the setup PR for you to review and merge
 
+### Trigger a one-shot run
+
+Once Outrider is installed, `remyxai outrider trigger` dispatches an ad-hoc run targeting a specific paper or method — see [docs/method-targeted-runs.md](docs/method-targeted-runs.md) for the discover → trigger workflow.
+
 ### Credentials
 
 **You set up two things, once:**
@@ -149,6 +153,9 @@ Run any command with `--help` for full flag listings and examples.
 | `remyxai interests toggle <id>` | Flip active/inactive |
 | `remyxai interests delete <id>` | Remove an interest |
 | `remyxai outrider init` | Install Outrider on a GitHub repo via the Remyx App |
+| `remyxai outrider setup-local` | Install Outrider via your own `gh` (no Remyx App) |
+| `remyxai outrider trigger` | Dispatch a one-shot Outrider run; supports `--pin-method` / `--pin-arxiv` |
+| `remyxai search query <text>` | Search the engine's research-asset catalog |
 | `remyxai search list` | List recently added research assets (papers + Docker images) |
 | `remyxai search info <arxiv-id>` | Asset details |
 

docs/method-targeted-runs.md

@@ -0,0 +1,75 @@
+---
+type: howto
+description: Discover a relevant paper or method, then dispatch a targeted Outrider run that implements it.
+tags: [outrider, cli, pin-method, pin-arxiv, workflow_dispatch]
+---
+
+# Method-targeted Outrider runs
+
+Once [Outrider](https://github.com/remyxai/outrider) is installed on a repo, you can dispatch a one-shot run targeting a specific paper or method — useful for kicking off an ad-hoc PR/Issue without waiting for the next scheduled run.
+
+The flow is two steps: **discover** an arxiv id you want implemented, then **trigger** the action with that id pinned.
+
+
+## 1. Discover
+
+### From the engine's recommendations for an interest
+
+```bash
+remyxai papers list --interest <uuid> --period week -n 10
+```
+
+Lists the engine's top recommendations for a Research Interest over the lookback window. Each entry shows the title, arxiv URL, and a relevance score. Note the arxiv id (e.g. `2410.20305v2`) of the candidate you want to implement.
+
+`remyxai papers digest` groups recommendations by interest if you want a cross-cutting view.
+
+### From a free-text search of the catalog
+
+```bash
+remyxai search query "knowledge distillation" -n 5
+```
+
+Searches the engine's research-asset catalog for matches against a method or topic. Useful when you have a method in mind but don't yet know the canonical paper.
+
+`remyxai search info <arxiv-id>` returns the full asset details (license, code repo, abstract) if you want to vet a candidate before triggering.
+
+
+## 2. Trigger
+
+```bash
+# Pin to a specific paper by arxiv id
+remyxai outrider trigger --repo owner/name --pin-method 2410.20305v2
+
+# Or describe the method — the action resolves it to the top arxiv hit
+remyxai outrider trigger --repo owner/name --pin-method "knowledge distillation"
+```
+
+`--pin-method` accepts either a literal arxiv id (`NNNN.NNNNN[vN]`) or a free-text method query.
+
+- When the input matches the arxiv-id shape, the action uses **direct asset lookup** — the paper doesn't need to already be in the repo's candidate pool.
+- When the input is free text, the action runs the engine's search and pins to the top hit.
+
+In both cases the LLM selection pass is bypassed and the resolved paper goes straight to the implementation phase (Phase A audit → Phase B convention pass → Phase C test gate).
+
+### Pre-flight
+
+The command refuses to dispatch on repos that haven't been initialized with Outrider. If Outrider isn't installed yet, you'll see:
+
+```
+Outrider is not installed on owner/name. Install it first:
+  remyxai outrider init --repo owner/name
+```
+
+### --pin-arxiv (legacy)
+
+`--pin-arxiv` is the older form: it pins to an arxiv id but requires the paper to already be present in the repo's candidate pool. `--pin-method` is a superset (it works on arxiv ids outside the pool, via direct asset lookup), so prefer it for new uses.
+
+The two flags are mutually exclusive — setting both is a usage error.
+
+### Other options
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--repo owner/name` | cwd's git remote | Target repo |
+| `--interest <uuid>` | the workflow's configured interest | Override the Research Interest for this run |
+| `--ref <branch>` | the repo's default branch | The git ref to dispatch against |

remyxai/cli/commands.py

@@ -24,7 +24,10 @@
     handle_interests_delete,
     handle_interests_toggle,
 )
-from remyxai.cli.outrider_actions import handle_outrider_init
+from remyxai.cli.outrider_actions import (
+    handle_outrider_init,
+    handle_outrider_trigger,
+)
 from remyxai.cli.outrider_local import handle_outrider_setup_local
 
 
@@ -690,5 +693,60 @@ def outrider_setup_local(
     )
 
 
+@outrider.command("trigger")
+@click.option("--repo", "repo", default=None,
+              help=(
+                  "Target repo as owner/name or a GitHub URL. Defaults to "
+                  "detecting from the current directory's git remote."
+              ))
+@click.option("--pin-method", "pin_method", default=None,
+              help=(
+                  "Method/technique query (e.g. \"knowledge distillation\") "
+                  "or a literal arxiv_id. The action's selection pass is "
+                  "bypassed and the resolved paper is implemented directly. "
+                  "Mutually exclusive with --pin-arxiv."
+              ))
+@click.option("--pin-arxiv", "pin_arxiv", default=None,
+              help=(
+                  "arxiv_id of a paper in the repo's candidate pool to "
+                  "implement directly. Use --pin-method for arxiv_ids not "
+                  "in the pool (it does a direct asset lookup)."
+              ))
+@click.option("--interest", "-i", "interest_id", default=None,
+              help="Override the ResearchInterest UUID for this run.")
+@click.option("--ref", "ref", default=None,
+              help="Git ref to dispatch on. Defaults to the repo's default "
+                   "branch.")
+def outrider_trigger(repo, pin_method, pin_arxiv, interest_id, ref):
+    """
+    Dispatch a one-shot Outrider run on a repo via workflow_dispatch.
+
+    Useful for kicking off ad-hoc method-targeted PRs without waiting for
+    the next scheduled run. The repo must already have an Outrider workflow
+    installed (see `remyxai outrider init` / `setup-local`). Authenticates
+    via your local `gh` CLI — no Remyx engine round-trip.
+
+    Examples:
+
+      # Implement a specific method on a target repo
+      remyxai outrider trigger --repo owner/name \\
+        --pin-method "knowledge distillation"
+
+      # Re-run a previously surfaced paper by arxiv_id (works even if it's
+      # no longer in the candidate pool)
+      remyxai outrider trigger --repo owner/name --pin-method 2410.20305v2
+
+      # Plain trigger — let the normal selection pass run
+      remyxai outrider trigger --repo owner/name
+    """
+    handle_outrider_trigger(
+        repo=repo,
+        pin_method=pin_method,
+        pin_arxiv=pin_arxiv,
+        interest_id=interest_id,
+        ref=ref,
+    )
+
+
 if __name__ == "__main__":
     cli()

remyxai/cli/outrider_actions.py

@@ -389,3 +389,155 @@ def handle_outrider_init(
             "  ⚠ No model provider key set — connect Claude Code so the first "
             "run can complete.", fg="yellow",
         )
+
+
+# ─── outrider trigger ─────────────────────────────────────────────────────
+
+WORKFLOW_FILENAME = "outrider.yml"
+
+
+def _gh_default_branch(repo: str) -> Optional[str]:
+    """Return the repo's default branch via `gh api`, or None on failure."""
+    try:
+        out = subprocess.check_output(
+            ["gh", "api", f"/repos/{repo}", "--jq", ".default_branch"],
+            text=True, stderr=subprocess.DEVNULL,
+        ).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+    return out or None
+
+
+def _outrider_workflow_exists(repo: str) -> bool:
+    """Return True iff the repo has an Outrider workflow registered.
+
+    Probes the Actions API rather than the Contents API: the Contents
+    endpoint reports the file as soon as it's committed, but the Actions
+    endpoint only knows about a workflow after GitHub has indexed it for
+    dispatch — which is the precise capability we need for the trigger
+    call to succeed.
+    """
+    r = subprocess.run(
+        ["gh", "api", f"/repos/{repo}/actions/workflows/{WORKFLOW_FILENAME}",
+         "--silent"],
+        capture_output=True, text=True,
+    )
+    return r.returncode == 0
+
+
+def _gh_dispatch_outrider(repo, branch, inputs):
+    """Dispatch the Outrider workflow with the supplied inputs.
+
+    Uses ``gh workflow run`` (not raw ``gh api``) because workflow_dispatch
+    expects inputs nested under ``inputs.*`` in the request body. The raw
+    POST endpoint accepts ``ref`` and ``inputs`` at the top level and
+    rejects any extra top-level keys with ``HTTP 422 "X is not a permitted
+    key"``; ``gh workflow run`` handles that wrapping for us.
+
+    Returns (ok, stderr) so the caller can map errors to user-facing hints.
+    """
+    args = [
+        "gh", "workflow", "run", WORKFLOW_FILENAME,
+        "--repo", repo, "--ref", branch,
+    ]
+    for k, v in inputs.items():
+        if v is None or v == "":
+            continue
+        args.extend(["-f", f"{k}={v}"])
+    r = subprocess.run(args, capture_output=True, text=True)
+    return (r.returncode == 0, (r.stderr or "").strip())
+
+
+def _gh_latest_run_url(repo, sleep=time.sleep):
+    """Best-effort lookup of the most recent outrider.yml run URL."""
+    for _ in range(5):
+        try:
+            url = subprocess.check_output(
+                ["gh", "run", "list", "--repo", repo,
+                 "--workflow", WORKFLOW_FILENAME, "--limit", "1",
+                 "--json", "url", "--jq", ".[0].url"],
+                text=True, stderr=subprocess.DEVNULL,
+            ).strip()
+            if url:
+                return url
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+        sleep(2)
+    return None
+
+
+def handle_outrider_trigger(
+    repo, pin_method, pin_arxiv, interest_id, ref,
+):
+    """Dispatch a one-shot Outrider run on a repo via workflow_dispatch.
+
+    Called from `commands.outrider_trigger`. Mirrors `outrider setup-local`
+    by using the user's authenticated `gh` to POST the dispatch — no Remyx
+    engine round-trip, no Remyx App requirement. The repo must already
+    have an Outrider workflow installed (set up via `remyxai outrider init`
+    or `setup-local`).
+    """
+    # Inputs validation
+    if pin_method and pin_arxiv:
+        raise click.UsageError(
+            "--pin-method and --pin-arxiv are mutually exclusive."
+        )
+
+    # Repo resolution
+    resolved_repo = _normalize_repo(repo) if repo else _detect_github_repo_from_cwd()
+    if not resolved_repo:
+        raise click.UsageError(
+            "Could not determine target repo. Pass --repo owner/name or run "
+            "from inside a GitHub-origin git checkout."
+        )
+
+    # Pre-flight: refuse to dispatch on repos that aren't initialized.
+    # Surfaces a clear install hint instead of a generic 404 from the
+    # workflow_dispatch call below — the error is structurally about the
+    # repo's setup state, not the dispatch attempt itself.
+    if not _outrider_workflow_exists(resolved_repo):
+        raise click.ClickException(
+            f"Outrider is not installed on {resolved_repo}. Install it "
+            f"first:\n"
+            f"  remyxai outrider init --repo {resolved_repo}\n"
+            f"or, if your org can't grant the Remyx GitHub App yet:\n"
+            f"  remyxai outrider setup-local --repo {resolved_repo}"
+        )
+
+    # Ref defaults to the repo's default branch (so trigger works without
+    # the user knowing whether the repo's default is main, master, develop).
+    branch = ref or _gh_default_branch(resolved_repo)
+    if not branch:
+        raise click.ClickException(
+            f"Could not resolve a ref for {resolved_repo}. Pass --ref "
+            f"explicitly (e.g. --ref main)."
+        )
+
+    inputs = {
+        "pin-method": pin_method or "",
+        "pin-arxiv": pin_arxiv or "",
+        "interest-id": interest_id or "",
+    }
+
+    click.echo(f"Dispatching Outrider on {resolved_repo} (ref={branch})…")
+    if pin_method:
+        click.echo(f"  pin-method: {pin_method!r}")
+    if pin_arxiv:
+        click.echo(f"  pin-arxiv:  {pin_arxiv!r}")
+    if interest_id:
+        click.echo(f"  interest:   {interest_id}")
+
+    ok, stderr = _gh_dispatch_outrider(resolved_repo, branch, inputs)
+    if not ok:
+        hint = ""
+        if "403" in stderr or "permission" in stderr.lower():
+            hint = ("\n  Your gh token lacks the scope to dispatch workflows "
+                    "on this repo. Re-auth: `gh auth login --scopes workflow`.")
+        raise click.ClickException(f"workflow dispatch failed: {stderr}{hint}")
+
+    click.secho("✓ Dispatched.", fg="green", bold=True)
+    url = _gh_latest_run_url(resolved_repo)
+    if url:
+        click.echo(f"  Run: {url}")
+    else:
+        click.echo(f"  Run: https://github.com/{resolved_repo}/actions")