dsh-cxas

Readme

# dsh-cxas

A **DeepSeek Harness (DSH) tool plugin** that wraps the
[CX Agent Studio Scripting API (CXAS SCRAPI)](https://github.com/GoogleCloudPlatform/cxas-scrapi)
command-line tool (`cxas`) as structured, model-facing tools. It lets a DSH
agent list apps, pull/push apps, run and export evaluations, list deployments,
inspect conversations/traces, and interact with tools/callbacks/variables —
directly through the `cxas` CLI.

> **DeepSeek Harness plugin** · category: Tools & Capabilities · license:
> Apache-2.0 · install with the [dsp CLI](https://deepseekplugin.org):
> `dsp install dsh-cxas`

## What it does

Each registered tool builds an `cxas <command>` argv, runs the binary as a
subprocess on the host, and returns a canonical result with `exitCode`,
`stdout`, `stderr`, and `command` so the model can reason about failures
and continue.

| Tool | Runs |
|---|---|
| `cxas_apps_list` | `cxas apps list` |
| `cxas_apps_get` | `cxas apps get <app>` |
| `cxas_create` | `cxas create <name>` |
| `cxas_delete` | `cxas delete <resource>` |
| `cxas_pull` | `cxas pull <app>` |
| `cxas_push` | `cxas push` |
| `cxas_lint` | `cxas lint` |
| `cxas_deployments_list` / `cxas_deployments_create` / `cxas_deployments_promote` | `cxas deployments ...` |
| `cxas_run_eval` | `cxas run <app>` |
| `cxas_eval_report` | `cxas evals report` |
| `cxas_eval_export` | `cxas export <evaluation_id>` |
| `cxas_push_eval` | `cxas push-eval <file>` |
| `cxas_conversations_list` / `cxas_conversations_get` | `cxas conversations ...` |
| `cxas_trace_list` / `cxas_trace_get` | `cxas trace ...` |
| `cxas_tools_list` / `cxas_tools_delete` | `cxas tools ...` |
| `cxas_callbacks_list` | `cxas callbacks list` |
| `cxas_variables_list` | `cxas variables list` |
| `cxas_help` | `cxas --help [topic]` |
| `cxas` (passthrough) | any `cxas ...` argv |

## Prerequisites

1. **cxas-scrapi installed and on `PATH`**:

   ```sh
   pip install cxas-scrapi
   cxas --help      # verify it runs
   ```

2. **Google Cloud application-default credentials** (or a service-account
   key via the SDK):

   ```sh
   gcloud auth application-default login
   gcloud config set project <your-project>
   ```

## Mounting the plugin

> **Restart required.** If a DSH web session is already running at
> `http://127.0.0.1:3080`, you must stop it and relaunch with the overlay for
> the new tools to appear. A running server does not pick up a new `--patch`.

### Option A — quick overlay (`--patch`)

From the directory that contains `dsh-cxas` (e.g. the workspace root):

```sh
pnpm dsh web --patch C:/Users/yashk/Downloads/nvidia/NVIDIA-Nexus/dsh-cxas/cordis.yml
# or, if `dsh` is installed (not run-from-source):
dsh web --patch C:/Users/yashk/Downloads/nvidia/NVIDIA-Nexus/dsh-cxas/cordis.yml
```

Open `http://127.0.0.1:3080` and ask the agent to, for example,
“Use `cxas_apps_list` to list the apps in my project.” If port `3080` is taken
by another instance, add `--port 3090 --no-open`.

The plugin `name` in `cordis.yml` is a `file://` URL — on Windows the ESM
loader rejects bare absolute paths like `C:/...`. If you move the plugin,
update `name` to point at its `src/index.ts` as a `file://` URL.

### Option B — install into a profile (bundle)

The package also declares `dsh.bundle`, so it can be installed permanently:

```sh
dsh plugin --profile demo add ./dsh-cxas
dsh --profile demo
```

See [Publishing a bundle](../../docs/user/develop/basic/publish.md) for the
build-script / `prepare` allowance notes if you install from git.

## Verification

A standalone smoke test drives `apply()` with a stub `tools` registry and
checks that the plugin registers all tools and that `execute()` successfully
invokes the real `cxas` binary (no DSH boot or credentials required):

```sh
# from the deepseek-harness checkout root:
node --import tsx/esm C:/Users/yashk/Downloads/nvidia/NVIDIA-Nexus/dsh-cxas/test-load.mjs
```

Expected: `registered 24 tools`, `cxas_help exitCode=0`, and correct argv for
`cxas_apps_list`, `cxas_lint`, and the `cxas` passthrough.

## Configuration

| Key | Default | Meaning |
|---|---|---|
| `cxasBin` | `cxas` | Path to the `cxas` executable. |
| `project` | — | Fallback `--project` appended to commands that accept it. |
| `location` | — | Fallback `--location` (e.g. `global`) appended to commands that accept it. |
| `timeoutMs` | `120000` | Timeout for one `cxas` invocation. |

Set values in the `config:` block of your `cordis.yml` / `cordis.patch.yml`.

## Notes & limitations

- The plugin shells out to the host `cxas` binary; it does **not** bundle or
  authenticate to Google Cloud itself.
- Tool parameter sets are a curated subset. For an unmapped command, use the
  `cxas` passthrough tool (its `args` array is passed through verbatim), or
  call `cxas_help` first to confirm exact flags.
- Mapped flag names are best-effort against the current CLI surface; if a flag
  is rejected, consult `cxas_help` and use the passthrough tool.

## Model Experience

Indirectly, through the tool schemas it registers: every tool contributes its
name, `description`, and parameter schema to the assembled system prompt, and
its `output.render` produces the model-facing result text. No additional
prompt sections are injected beyond the tool catalog itself.

#### KV Cache effect

Does not invalidate a reusable prefix. The plugin adds no request-prefix
content at boot; the only model-visible text is per-call tool description and
result content, which is data-dependent and independent of prior requests.