dsh-seismicx

A DeepSeek Harness plugin that exposes the
SeismicX earthquake-catalog skill as typed,
model-facing tools.

The skill's SKILL.md stays the portable workflow document — it runs unchanged on Claude Code,
Codex, and OpenCode. This plugin is the DSH-only enhancement layer over it, and it exists for
three things a skill cannot do:

	As a skill	As this plugin
Arguments	A bash string; a bad --real-R tuple fails minutes in	Validated at the call boundary, before the process starts
Results	stdout prose the model re-parses for paths	A typed JSON value with picks_path, map_path, exit_code
Hour-long picks	A blocking bash call that floods the context window	A background job with an id, job_status, and job_kill

Install

Requires a working seismicx-catalog-skill checkout and its Python environment.

From a local checkout (simplest)

lib/ is not committed, so build once, then install the directory:

git clone https://github.com/MOLAaaaaaaa/dsh-seismicx && cd dsh-seismicx && npm install && npm run build

dsh plugin --profile <name> add /absolute/path/to/dsh-seismicx

pnpm links the checkout, so it uses the lib/ you just built and needs no build permission.

From GitHub

A git install fetches sources, not build output, so pnpm has to run this package's prepare
script — and pnpm ≥10 refuses to do that until you allow it by name. The first add fails and
prints the key; put it in the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-seismicx: true

then re-run, pinning a commit so a later push cannot silently change what executes:

dsh plugin --profile <name> add github:MOLAaaaaaaa/dsh-seismicx#<sha>

That allowance is permission to execute this package's code on your machine at install time,
outside any sandbox the agent runs under. prepare here is transpile-only (tsc --noCheck), so it
cannot fail from peer-version drift the way a type-checking build would.

Configure

Point the plugin at the skill in the profile's cordis.patch.yml:

- id: seismicx
  config:
    skillRoot: /absolute/path/to/seismicx-catalog-skill
    python: /path/to/.venv/bin/python
    workdir: /path/to/your/project

The shipped cordis.patch.yml reads SEISMICX_SKILL_ROOT and SEISMICX_PYTHON from the
environment instead, if you would rather not write the path into a file.

Verify the wiring without touching any data:

dsh --profile <name> --dump-config   # the seismicx row should appear

then ask the agent to call seismicx_list_models.

Config

Field	Default	Description
skillRoot	— (unset ⇒ inert)	Absolute path to the skill checkout
python	python3	Interpreter used for every subcommand
workdir	.	Directory relative output paths resolve against
listModels / scan / pick / plotMap	true	Register the corresponding tool
allowBackground	true	Let seismicx_pick publish background jobs
quickTimeoutMs	120000	Budget for metadata subcommands
pickTimeoutMs	3600000	Budget for a foreground pick
plotTimeoutMs	600000	Budget for map rendering

Unconfigured and misconfigured behave differently, on purpose:

• skillRoot unset — the plugin logs one line and registers no tools. Installing this bundle
  can never stop the harness from booting; an installed-but-not-yet-pointed-at plugin is
  unconfigured, not broken.
• skillRoot set but relative — fails loud at load, naming the offending row. That is genuine
  misconfiguration, and the error belongs where it identifies the row rather than inside a tool
  call the model has to interpret.

Existence is deliberately not checked — the path may live in a sandbox or remote execution world
this process cannot stat, and ctx.subprocess is what resolves it.

The profile's cordis.patch.yml is watched, so correcting skillRoot or python takes effect
without restarting dsh web.

Tools

Tool	Shape	Notes
seismicx_list_models	foreground, concurrency-safe	Call it first to verify skillRoot/python
seismicx_scan	foreground, concurrency-safe	Waveform inventory; confirms the archive is readable
seismicx_pick	foreground or background	Set run_in_background for continuous data
seismicx_plot_map	foreground, concurrency-safe	Returns map_path; carries presentationMeta for a UI card

seismicx_pick exposes no filtering argument, on purpose: the skill's standing rule is that
continuous waveforms reach the PNSN picker unfiltered.

A background pick is owned by the calling agent, so agent disposal cancels and awaits it. A call
with no agent behind it (a direct service invocation rather than a model turn) is refused rather
than leaking a multi-hour unowned run.

Design notes

Everything goes through ctx.subprocess, never node:child_process. The seam is what carries
the deployment's sandbox and remote-execution choices, so a composition that points subprocess at
a remote runner moves these tools with it, unchanged.

argv is an array and is never shell-interpreted. A station code or path containing shell
metacharacters cannot escape into a command line.

A non-zero exit is a domain outcome, not a throw. It is represented in the canonical value
(exit_code, stderr_tail) so callers can branch on it. Only spawn-level failures reject.

The Python process is not confined. Confinement is a consumer responsibility in this
architecture — ctx.shell's sandbox providers wrap argv before handing it to ctx.subprocess, and
this plugin does not do that wrapping. Treat these tools as carrying the same trust level as the
bash tool: they run the interpreter you configured, with your ambient filesystem and network
access. Routing argv through a ctx.sandbox backend is listed below as deferred work.

Not done yet

• The remaining nine subcommands. polarity, associate, locate, magnitude-ml,
  mechanism, analyze, build-tools, init-config, and the end-to-end catalog follow the
  same shape as seismicx_scan; adding one is mechanical.
• Structured returns are shallow. Tools report the paths they were given plus exit facts, not
  row counts or residual statistics, because the CLI prints prose. The clean fix belongs upstream:
  a --json summary flag on the Python subcommands, which this plugin would then surface as typed
  fields instead of stdout_tail.
• No browser half. seismicx_plot_map already persists presentationMeta.mapPath, which is
  what a tool.call.toolview entry keyed seismicx_plot_map needs to render the map inline in the
  conversation instead of leaving a path to open. A GMT/PyGMT renderer and a shell.overlay
  control panel (region, projection, depth slice, beachballs) are the intended next step.
• No sandbox wrapping. ctx.subprocess is called directly, so the interpreter runs unconfined
  (see the design note above). Wrapping argv through a ctx.sandbox backend would confine it, at
  the cost of having to widen the policy for the GPU, model cache, and build-tools network access
  the pipeline legitimately needs.
• No capability seams. The picker, associator, locator, and mechanism engines are still CLI
  flags rather than swappable ctx.* providers. Seam-ifying them is what would let a freshly
  fine-tuned checkpoint become a plugin row instead of a code change.

License

GPL-3.0-only — see LICENSE.

This plugin is distributed under GPL-3.0 because the skill it wraps is GPL-3.0. DeepSeek Harness
itself is MIT and is not covered by this license; MIT is one-way compatible with GPL, so a GPL
plugin may run on an MIT harness, but this plugin's code cannot be relicensed into the harness
repository.

The bundled model checkpoints in the skill carry their own separate terms; see the .LICENSE files
beside them in assets/models/.