/remote-compute-ssh

name: remote-compute-ssh
description: Submit recoverable SSH-direct research Runs with live progress cards and model-free monitoring.
license: Apache-2.0

Remote compute over SSH

Use this skill after choosing an `ssh:<alias>` execution context. Wisp owns the job lifecycle locally: `run_in_context` creates the Run record, stages explicit inputs with persisted byte progress, and starts a detached supervisor on the server. The Runs panel and SQLite record remain authoritative if the conversation ends or Wisp restarts.

Dispatch workflow

1. Use short `run_in_context` calls for read-only discovery such as `nvidia-smi -L`, `which python3`, or `module avail`. Free-form shell SSH is disabled. Use the interpreter path reported by the context probe; do not assume a `python` alias exists when the probe found `python3`. 2. Put the real command in one `run_in_context` call. Include environment activation in the command so the Run is reproducible. 3. To watch the Run or wait for later work, call `monitor_run` with the returned Run id. Wisp inserts a live card in the conversation, suspends the tool without additional model calls, and resumes the same agent turn with the terminal result. If the result has `wait_interrupted: true`, the remote process is still running: answer the user from the snapshot, then call `monitor_run` again with the same id. Do not resubmit. Use `cancel_run` only when the user asked to stop. For fire-and-forget work, report the Run id and end the turn instead. 4. Use `get_run` only for one explicit status snapshot; never call it repeatedly to wait. Use `cancel_run` when the user asks to stop.

Never monitor a Run with `Start-Sleep`, `sleep`, `ssh ... ps`, `kill -0`, a shell polling loop, `nohup`, background `&`, or hand-written PID files. Those duplicate the control plane and can strand the agent turn. A transient SSH error is stored as `last_poll_error`; do not resubmit, because Wisp retries the same idempotent remote handle.

{
  "context_id": "ssh:gpu-box",
  "title": "Motif enrichment across 2,000 backgrounds",
  "command": "source ~/miniforge3/etc/profile.d/conda.sh && conda activate genomics && python motif_enrichment_analysis.py",
  "timeout_secs": 14400,
  "input_paths": ["scripts/motif_enrichment_analysis.py"]
}

Then, when live monitoring is needed:

{ "run_id": "<id returned by run_in_context>" }

Pass that object to `monitor_run`. The call may remain suspended for hours; it does not consume model tokens while the Run Manager watches the job. If `wait_interrupted` is true, respond from the snapshot and call `monitor_run` again with the same id; do not resubmit.

`input_paths` are project-relative local files. Wisp validates them, copies them into an isolated `inputs/` directory, and flattens them to their basenames. The command starts in that directory, so the example above can use the staged script by basename. Upload progress, throughput, and ETA appear in the Run card. For a large dataset already on the server, reference its absolute remote path in `command`; do not copy it back to the laptop just to send it out again.

A remote command or application exiting non-zero is normal exploration after a successful login. Read stderr, correct the command from the probed capabilities, and continue. Stop only when SSH rejects authentication or host trust; do not repeat a rejected login with guessed credentials or SSH options.

The control directory is `~/.wisp-science/runs/<run-id>` and the command starts in its `inputs/` subdirectory. stdout and stderr are tailed into the Run record. The SSH supervisor requires `setsid`, GNU-compatible `timeout`, `bash`, and `/proc`; a missing prerequisite fails the Run instead of running without a wall-time limit. Wisp maps the supervisor timeout marker to `timed_out`.

Results

Declare `output_specs` with workdir-relative globs for the final products. After the Run succeeds, Wisp collects the matches on the server, checksums them, pulls them back through a persisted transfer Run, places them under the project's configured results directory, and registers each as an ArtifactVersion. The Run records `harvested_at` once registration completes; `harvest_run({"run_id":"..."})` retries a failed or interrupted harvest.

Selection is the database boundary: only spec-matched outputs are transferred and recorded. Point globs at final products (for example `Trinity.fasta`), never at intermediate trees. A non-bundle glob may match at most 500 files. For a many-file output that must be kept, set `bundle: true` so the matches (or a whole directory) arrive as one tar.gz archive registered as a single artifact:

{
  "output_specs": [
    { "glob": "results/*.tsv", "kind": "table", "residency": "auto" },
    { "glob": "assembly_out", "kind": "archive", "residency": "local", "bundle": true }
  ]
}

Files over the size caps (or `residency: "remote"`) are moved out of the run workdir into the project's persistent remote data area, registered as `ssh://` references with checksum and size, and ledgered so they stay visible in `list_remote_files`. Workspace cleanup never orphans them. Delete a ledgered persist file with `remove_remote_files` only after the user confirms they no longer need it — that marks the artifact's source discarded. Explicit `ssh://…` URIs in `output_specs` still register a remote reference without any download.

Cleanup: servers are disposable

Tasks and artifacts belong to the project; the server only computes. After the results are harvested (or knowingly abandoned), reclaim the workspace:

• `cleanup_run_workspace({"run_id":"..."})` deletes the Run's

`~/.wisp-science/runs/<run-id>` directory (inputs, logs, intermediates). A succeeded Run with declared `output_specs` must be harvested first; the tool refuses otherwise so results are never lost. Registered artifacts stay in the project. Before deletion Wisp pulls a trailing slice of stdou