dsh-ecat

Two DSH commands over the ECAT refinement loop.

| Command | What it does | |---|---| | /ecat-setup | Hands a prompt to the agent, which runs the ecat-setup skill: interview, profile, scoring plugins | | /ecat-refine | Runs the ecat-refine scripts directly: status, open, preflight, start, stop |

/ecat-setup never writes files itself — every write goes through the agent, so the normal approval and sandbox rules apply. /ecat-refine only executes fixed subcommands with an argv array; the raw input is never passed to a shell.

Install

dsh plugin --profile <profile> add dsh-ecat

Or add the market index source and install from the discovers page. The package is MIT licensed; its full contents are the two skills, the ECAT wheel, and the command code.

Requirements

• DSH ^0.2.1-rc.2
• Python 3.11+ somewhere on the host (python3, python, or the py launcher)

ECAT itself is not a prerequisite: the package ships assets/wheels/ecat-*.whl and /ecat-setup creates ~/.dsh/ecat-venv, installs the wheel into it with uv pip (falling back to python -m venv + pip), and points every later command at that interpreter. Dependencies are resolved from the network on that first run, which is why the installation lives in setup rather than in the loop commands: configuration is the point where a missing environment should surface, not the first status check.

If the environment cannot be prepared, /ecat-setup fails before asking any questions and reports the uv and pip errors; /ecat-refine has no install step of its own.

If you already installed ECAT globally (uv tool install --editable <repo>), the plugin uses that interpreter instead and never creates a venv.

Configuration

| Key | Default | Meaning | |---|---|---| | pythonPath | auto | Interpreter to use. When set it always wins, broken or not. | | ecatPath | ecat | The CLI, used only for preflight's availability check. | | workspaceRoot | empty | Fixed ECAT workspace; otherwise the hand-off file or session cwd. | | uvPath | uv | Used by /ecat-setup to build the venv. Falls back to python -m venv. |

ECAT_VENV_DIR relocates the managed environment; tests and multi-user machines use it.

Usage

/ecat-setup
/ecat-setup help
/ecat-refine status
/ecat-refine preflight
/ecat-refine start
/ecat-refine open
/ecat-refine stop

Both commands advertise their arguments in the composer hint as soon as you type the name: /ecat-setup [help | <task description>] and /ecat-refine [help | status | open | start | stop | preflight] [workspace].

/ecat-refine with no subcommand prints the same list as /ecat-refine help. /ecat-refine run starts the runtime-selection conversation explicitly.

Help output is echoed back through one agent turn. DSH's chat view treats a session whose only nodes are commands as blank and shows the welcome screen, so a command that merely returns text stays invisible until something creates a conversation turn.

Worked example — /ecat-setup help

The environment check lives here, not on /ecat-refine, because that is where you go when you want to know whether the Python side is usable and where a short wait is expected. Real output, DSH 0.2.1-rc.2, plugin 0.1.0-alpha.1, Windows:

Usage: /ecat-setup [help | <task description>]
  no argument   interview me about the task, then write profile and plugins
  <text>        same, reusing what this message already says about the task
  help          this text, plus whether every ECAT dependency is usable

interpreter: C:\Users\me\.dsh\ecat-venv\Scripts\python.exe
python: 3.11.13
environment: ready — all 13 runtime dependencies usable
  anthropic 2.1.0
  typer 0.27.3
  ...
ecat: C:\Users\me\.dsh\ecat-venv\Lib\site-packages\ecat\__init__.py

The list is not hard-coded: src/probe_deps.py reads the installed wheel's own Requires-Dist entries through importlib.metadata, so a dependency added to pyproject.toml is covered the next time the wheel is built. Each entry is checked for presence, for the version range the wheel asks for, and for a resolvable top-level module. A failure names the package and how to fix it:

environment: NOT ready — 2 of 13 dependencies failed
  openpyxl is not installed
  pydantic has version 2.6.1, needs pydantic>=2.7
  fix with: <interpreter> -m pip install openpyxl

This is deliberately not import ecat: ecat/__init__.py is a version string, so importing it succeeds with every third-party package missing. resolvePython uses the same probe when it chooses an interpreter, so a half-installed environment is never picked for status, start, or anything else.

Before the first setup it reads environment: NOT ready — <venv> does not exist. and tells you to run /ecat-setup with no argument. Nothing is installed and no interview starts from help.

Worked example — /ecat-refine help

Usage: /ecat-refine [status|open|start|stop|preflight] [workspace]
  status     latest run: H, iterations, worst dimension (default)
  ...
No subcommand runs the loop: the agent picks the runtime with you first.
Check the environment with /ecat-setup help; /ecat-refine has no install step.

This is synchronous — it does not spawn Python, so it answers immediately even when no interpreter can import ECAT.

Worked example — a common failure

/ecat-refine status with no workspace configured and no hand-off file:

kind: error
No ECAT workspace found. Run /ecat-setup first, pass it explicitly
(/ecat-refine status <workspace>), or set workspaceRoot in the plugin config.

This is the path a first-time user hits; it names all three ways to resolve it rather than silently reading the session's cwd, which could start the loop on the wrong tree.

Failure modes

| Symptom | Cause | |---|---| | No ECAT workspace found | /ecat-setup has not run and no workspace was passed | | spawn failed: ENOENT | pythonPath does not exist on the DSH host | | preflight exit 15 | ecat is not on the host PATH | | preflight exit 13 | the variable named by api_key_env has no value in <ws>/.env |