rtk-for-dsh 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# rtk-for-dsh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A connector that lets [DeepSeek Harness](../../cloned/deepseek-harness) run shell commands through [RTK](../../cloned/rtk-projects/rtk) (Rust Token Killer), so command output reaches the model filtered and compressed.
+
+## What it provides
+
+`rtk-for-dsh` provides two bash executors for the DSH shell seam (`ctx.shell`). Each replaces the executor a composition mounts; the seam allows exactly one.
+
+- `RtkBashExecutor` replaces `@deepseek-ai/dsh-bash-local`.
+- `RtkSandboxBashExecutor` replaces `@deepseek-ai/dsh-bash-sandbox`. The DeepSeek Harness desktop profile mounts the sandbox variant (from `packages/bundle/base`), so use this one there.
+
+For each command, the executor asks `rtk rewrite <command>` and acts on the exit code:
+
+| `rtk rewrite` exit | Executor behaviour |
+|---|---|
+| `0` (allow) or `3` (ask, the default when no allow rules exist) | Runs the rewritten command, e.g. `git status` becomes `rtk git status`. |
+| `1` (no rewrite) | Runs the command as written. |
+| `2` (deny rule matched) | Does not run it. Returns exit `126` with `rtk: command refused by an RTK deny rule` on stderr. |
+| missing binary, timeout, abort, other code | Runs the command as written. RTK is an output filter, so its absence never blocks the agent. |
+
+Spawning, output caps, timeouts, cancellation and background jobs are inherited unchanged from `LocalBashExecutor`.
+
+## Install package
+
+`npm pack` builds a tarball (`lib/` JS and types, `cordis.patch.yml`, README). Install it into a profile with:
+
+```bash
+npm install ./rtk-for-dsh-dsh-rtk-bash-0.1.0.tgz
+```
+
+The package declares its DeepSeek Harness packages (`dsh-bash-local`, `dsh-bash-sandbox`, `dsh-shell`, `cordis`, `schemastery`) as **optional peers**. They must be resolvable from the profile for the executor to load. npm has them only at `0.0.1-rc.1`, not at the app's runtime version, and their published peer metadata is broken, so npm does not install them for you.
+
+- Entries: `rtk-for-dsh` (`RtkBashExecutor`, replaces `dsh-bash-local`) and `rtk-for-dsh/sandbox` (`RtkSandboxBashExecutor`, replaces `dsh-bash-sandbox`).
+- `cordis.patch.yml` is the `dsh.bundle.patch` layer. It disables `bash-sandbox` and inserts `rtk-bash-sandbox`.
+
+```bash
+npm run build                                          # emits lib/; unexpected type errors fail
+DSH_ROOT=/path/to/deepseek-harness npm run typecheck   # checks src/ against the DSH sources
+npm test
+```
+
+## Layout
+
+```
+src/rewrite.ts        rtk rewrite client (no DSH dependency; unit-tested)
+src/executor.ts       RtkBashExecutor (extends LocalBashExecutor) and RtkSandboxBashExecutor (extends SandboxBashExecutor)
+src/index.ts          exports
+src/rewrite.test.ts   tests: fake rtk binaries plus the real rtk
+tests/                DSH-side specs (run inside a deepseek-harness workspace)
+```
+
+## Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `rtkEnabled` | `true` | `false` makes the executor behave as `dsh-bash-local`. |
+| `rtkBin` | `rtk` | RTK executable, resolved through PATH. |
+| `rewriteTimeoutMs` | `2000` | Upper bound for one `rtk rewrite` call. |
+
+The local bash fields (`cwd`, `timeoutMs`, `maxTimeoutMs`, `maxOutputBytes`, `maxSpillBytes`, `graceMs`) keep their `dsh-bash-local` meanings and defaults.
+
+## Wiring into a DSH composition
+
+Replace the executor entry in your profile. Keep the environment registry and the bash tool as they are:
+
+```yaml
+- name: 'rtk-for-dsh'   # instead of '@deepseek-ai/dsh-bash-local'
+  config:
+    rtkEnabled: true
+- name: '@deepseek-ai/dsh-shell-env'
+- name: '@deepseek-ai/dsh-tool-bash'
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+The suite runs `rtk` for real when it is on PATH, or at `RTK_BIN` when set. Other cases use fake binaries.
+
+## Status and limits
+
+- Verified against deepseek-harness sources (commit `fcc0ad4621`, `pnpm install --frozen-lockfile`):
+  - `executor.ts` typechecks with `noImplicitOverride` and no errors in its own files or in `packages/shell/*`. The typecheck maps `@deepseek-ai/*` to the workspace sources, using a loose compiler configuration.
+  - 6 end-to-end cases in `tests/executor.dsh.spec.ts` pass under DSH's vitest setup. They cover: a rewrite replaces the command that runs; exit 1 runs the original; a denial is refused with exit 126 and the command does not run; a missing rtk falls back to the original; `rtkEnabled: false` skips rtk; a rewritten command's exit code is passed through. A seventh case runs `git status` through the real rtk 0.43.0 and gets rtk's compact output.
+  - Through the agent loop: `tests/session.dsh.spec.ts` mounts the executor with the real `dsh-tool-bash`, and a scripted mock model calls `bash`. Results: real rtk returns `git status` in its compact form; a plain `echo` runs normally; a deny verdict reaches the model as stderr `rtk: command refused by an RTK deny rule` with `[exit code: 126]`, and the command does not run. No DeepSeek API key is needed for this test.
+- `tests/sandbox.dsh.spec.ts` runs the sandbox variant through the same mock-model harness: `git status` through real rtk, a plain `echo`, and the deny path all pass.
+- Sandbox confinement is **not** verified. A probe that wrote a file outside the workspace succeeded with rtk disabled and with the stock `SandboxBashExecutor`, so this test harness does not enforce the sandbox. Check confinement in the real desktop app before relying on it.
+- Not verified: a live DeepSeek model session (no API key in this environment), loading the executor from a DSH `cordis.yml` profile, a DSH typecheck after the sandbox-variant change, and DSH's strict `tsconfig.host.json` typecheck.
+- Its `Config` schema repeats the base `LocalBashExecutor` fields because schemastery's object extension is not used here. If the base defaults change, update the copy.
+- The `ask` verdict (exit 3) runs the rewritten command without a prompt, since DSH has no shell permission prompt of its own. Escalation prompts in DSH come from the sandbox path and are not affected.
+- The rewrite runs under the plugin process's environment and rule set, not under the session's workdir. RTK reads its rules from the Claude settings it finds on the machine.
+- Only `rtk rewrite` is used. The installed RTK here is 0.43.0; the checkout at `rtk-projects/rtk` is 0.49.0. Re-run the tests after upgrading.

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# Patch layer for profiles built on dsh-base: route the model's bash commands
+# through RTK, keeping the sandboxed executor (the one the desktop profile uses).
+# Mounting this layer replaces dsh-bash-sandbox with the RTK-routed variant; the
+# seam allows one executor, so the stock sandbox entry is disabled here.
+- id: bash-sandbox
+  disabled: true
+
+- insert:
+    - id: rtk-bash-sandbox
+      name: 'rtk-for-dsh/sandbox'
+      config:
+        rtkEnabled: true
+        rtkBin: rtk
+        rewriteTimeoutMs: 2000

package/lib/executor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DeepSeek Harness bash executors that route each command through RTK.
+ *
+ * Two variants share one routing step, so each keeps its base executor's
+ * behaviour:
+ * - {@link RtkBashExecutor} extends `LocalBashExecutor` (`dsh-bash-local`).
+ * - {@link RtkSandboxBashExecutor} extends `SandboxBashExecutor`
+ *   (`dsh-bash-sandbox`), which the desktop profile mounts. Use this one where
+ *   file confinement must stay in force.
+ *
+ * Before a command runs, `rtk rewrite` decides whether it runs as written, runs
+ * as an RTK-wrapped equivalent (for example `git status` to `rtk git status`),
+ * or is refused by an RTK deny rule. The base executor then runs the chosen
+ * command with its own deadline, output, and sandbox handling.
+ * @module rtk-for-dsh
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import type { ShellExecSpec, ShellExecution } from '@deepseek-ai/dsh-shell';
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local';
+import type { Config as LocalBashConfig } from '@deepseek-ai/dsh-bash-local';
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox';
+/** Plugin settings added to the local bash executor's settings. */
+export interface RtkConfig {
+    /** Route commands through `rtk rewrite`; when false the executor behaves as its base. */
+    rtkEnabled: Volatile<boolean>;
+    /** RTK executable (default `rtk`, resolved through PATH). */
+    rtkBin: Volatile<string>;
+    /** Upper bound for one `rtk rewrite` call; on expiry the command runs unchanged. */
+    rewriteTimeoutMs: Volatile<number>;
+}
+export type Config = LocalBashConfig & RtkConfig;
+export declare class RtkBashExecutor extends LocalBashExecutor {
+    static Config: any;
+    readonly config: Config;
+    execute(spec: ShellExecSpec): Promise<ShellExecution>;
+}
+export declare class RtkSandboxBashExecutor extends SandboxBashExecutor {
+    static Config: any;
+    readonly config: Config;
+    execute(spec: ShellExecSpec): Promise<ShellExecution>;
+}
+export default RtkBashExecutor;

package/lib/executor.js

@@ -0,0 +1,69 @@
+/**
+ * DeepSeek Harness bash executors that route each command through RTK.
+ *
+ * Two variants share one routing step, so each keeps its base executor's
+ * behaviour:
+ * - {@link RtkBashExecutor} extends `LocalBashExecutor` (`dsh-bash-local`).
+ * - {@link RtkSandboxBashExecutor} extends `SandboxBashExecutor`
+ *   (`dsh-bash-sandbox`), which the desktop profile mounts. Use this one where
+ *   file confinement must stay in force.
+ *
+ * Before a command runs, `rtk rewrite` decides whether it runs as written, runs
+ * as an RTK-wrapped equivalent (for example `git status` to `rtk git status`),
+ * or is refused by an RTK deny rule. The base executor then runs the chosen
+ * command with its own deadline, output, and sandbox handling.
+ * @module rtk-for-dsh
+ */
+import z from '@deepseek-ai/schemastery';
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local';
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox';
+import { rewriteCommand } from './rewrite.js';
+/** Script run in place of a command that an RTK deny rule refused. */
+const DENY_SCRIPT = "printf '%s\\n' 'rtk: command refused by an RTK deny rule' >&2; exit 126";
+/** Settings schema shared by both variants. Mirrors LocalBashExecutor.Config field for field. */
+const configSchema = z.object({
+    cwd: z.string().volatile(),
+    timeoutMs: z.number().default(120_000).volatile(),
+    maxTimeoutMs: z.number().default(600_000).volatile(),
+    maxOutputBytes: z.number().default(64_000).volatile(),
+    maxSpillBytes: z.number().default(64 * 1024 * 1024).volatile(),
+    graceMs: z.number().default(3_000).volatile(),
+    rtkEnabled: z.boolean().default(true).volatile(),
+    rtkBin: z.string().default('rtk').volatile(),
+    rewriteTimeoutMs: z.number().default(2_000).volatile(),
+});
+/**
+ * Apply RTK's verdict to a resolved spec. Denied commands become a script that
+ * exits 126 without running the original command.
+ * @param config - the live RTK settings.
+ * @param spec - the resolved spec from the base executor's `resolve()`.
+ * @returns the spec to hand to the base executor's `execute()`.
+ */
+async function routeSpec(config, spec) {
+    if (!config.rtkEnabled.get())
+        return spec;
+    const verdict = await rewriteCommand(spec.command, {
+        bin: config.rtkBin.get(),
+        timeoutMs: config.rewriteTimeoutMs.get(),
+        signal: spec.signal,
+    });
+    switch (verdict.kind) {
+        case 'rewritten': return { ...spec, command: verdict.command };
+        case 'denied': return { ...spec, command: DENY_SCRIPT };
+        case 'unchanged': return spec;
+    }
+}
+export class RtkBashExecutor extends LocalBashExecutor {
+    // schemastery has no object-extension helper, so the base fields are repeated in configSchema.
+    static Config = configSchema;
+    async execute(spec) {
+        return super.execute(await routeSpec(this.config, spec));
+    }
+}
+export class RtkSandboxBashExecutor extends SandboxBashExecutor {
+    static Config = configSchema;
+    async execute(spec) {
+        return super.execute(await routeSpec(this.config, spec));
+    }
+}
+export default RtkBashExecutor;

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Package entry. The default export is {@link RtkBashExecutor}, which replaces
+ * `dsh-bash-local`. For the sandboxed executor, use `rtk-for-dsh/sandbox`.
+ * @module rtk-for-dsh
+ */
+export { rewriteCommand } from './rewrite.ts';
+export type { RewriteOptions, RewriteVerdict } from './rewrite.ts';
+export { RtkBashExecutor, RtkSandboxBashExecutor, default } from './executor.ts';
+export type { Config, RtkConfig } from './executor.ts';

package/lib/index.js

@@ -0,0 +1,7 @@
+/**
+ * Package entry. The default export is {@link RtkBashExecutor}, which replaces
+ * `dsh-bash-local`. For the sandboxed executor, use `rtk-for-dsh/sandbox`.
+ * @module rtk-for-dsh
+ */
+export { rewriteCommand } from './rewrite.js';
+export { RtkBashExecutor, RtkSandboxBashExecutor, default } from './executor.js';

package/lib/rewrite.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Client for `rtk rewrite`, the single rewrite registry RTK exposes to
+ * delegates. The exit code carries the policy verdict:
+ *
+ * | Exit | Stdout    | Meaning                                              |
+ * |------|-----------|------------------------------------------------------|
+ * | 0    | rewritten | Rewrite; the allow rules cover the command.          |
+ * | 1    | (none)    | No rewrite applies; run the command as written.      |
+ * | 2    | (none)    | A deny rule matched; do not run the command.         |
+ * | 3    | rewritten | Rewrite; the host would normally ask (default case). |
+ *
+ * Any other outcome (missing binary, timeout, abort, unexpected exit code)
+ * resolves to `unchanged`, so the original command runs. RTK is an output
+ * filter; its absence must not block the agent.
+ */
+export type RewriteVerdict = {
+    kind: 'unchanged';
+} | {
+    kind: 'rewritten';
+    command: string;
+} | {
+    kind: 'denied';
+};
+export interface RewriteOptions {
+    /** RTK executable, resolved through PATH when not absolute. */
+    bin: string;
+    /** Upper bound for the `rtk rewrite` process. */
+    timeoutMs: number;
+    /** Cancels the rewrite; an aborted rewrite resolves to `unchanged`. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Ask RTK how to run `command`.
+ * @param command - the shell command exactly as the agent wrote it.
+ * @param options - binary, timeout and cancellation.
+ * @returns the verdict; never rejects.
+ */
+export declare function rewriteCommand(command: string, options: RewriteOptions): Promise<RewriteVerdict>;

package/lib/rewrite.js

@@ -0,0 +1,57 @@
+/**
+ * Client for `rtk rewrite`, the single rewrite registry RTK exposes to
+ * delegates. The exit code carries the policy verdict:
+ *
+ * | Exit | Stdout    | Meaning                                              |
+ * |------|-----------|------------------------------------------------------|
+ * | 0    | rewritten | Rewrite; the allow rules cover the command.          |
+ * | 1    | (none)    | No rewrite applies; run the command as written.      |
+ * | 2    | (none)    | A deny rule matched; do not run the command.         |
+ * | 3    | rewritten | Rewrite; the host would normally ask (default case). |
+ *
+ * Any other outcome (missing binary, timeout, abort, unexpected exit code)
+ * resolves to `unchanged`, so the original command runs. RTK is an output
+ * filter; its absence must not block the agent.
+ */
+import { execFile } from 'node:child_process';
+const EXIT_ALLOW = 0;
+const EXIT_DENY = 2;
+const EXIT_ASK = 3;
+/**
+ * Ask RTK how to run `command`.
+ * @param command - the shell command exactly as the agent wrote it.
+ * @param options - binary, timeout and cancellation.
+ * @returns the verdict; never rejects.
+ */
+export function rewriteCommand(command, options) {
+    return new Promise((resolve) => {
+        execFile(options.bin, ['rewrite', command], {
+            timeout: options.timeoutMs,
+            encoding: 'utf8',
+            windowsHide: true,
+            ...options.signal !== undefined ? { signal: options.signal } : {},
+        }, (error, stdout) => {
+            const code = exitCodeOf(error);
+            if (code === EXIT_DENY) {
+                resolve({ kind: 'denied' });
+                return;
+            }
+            if (code === EXIT_ALLOW || code === EXIT_ASK) {
+                const rewritten = stdout.replace(/\r?\n$/, '');
+                resolve(rewritten.length > 0 && rewritten !== command
+                    ? { kind: 'rewritten', command: rewritten }
+                    : { kind: 'unchanged' });
+                return;
+            }
+            // Exit 1 (no rewrite), or no numeric exit code (spawn failure, timeout, abort).
+            resolve({ kind: 'unchanged' });
+        });
+    });
+}
+/** The numeric exit code of a finished `execFile`, or `undefined` for spawn failures and signals. */
+function exitCodeOf(error) {
+    if (error === null)
+        return EXIT_ALLOW;
+    const code = error.code;
+    return typeof code === 'number' ? code : undefined;
+}

package/lib/sandbox.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sandboxed entry point: the default export is {@link RtkSandboxBashExecutor},
+ * for profiles that mount `dsh-bash-sandbox` (the desktop profile does).
+ * @module rtk-for-dsh/sandbox
+ */
+export { RtkSandboxBashExecutor, default } from './executor.ts';
+export type { Config, RtkConfig } from './executor.ts';

package/lib/sandbox.js

@@ -0,0 +1,6 @@
+/**
+ * Sandboxed entry point: the default export is {@link RtkSandboxBashExecutor},
+ * for profiles that mount `dsh-bash-sandbox` (the desktop profile does).
+ * @module rtk-for-dsh/sandbox
+ */
+export { RtkSandboxBashExecutor, default } from './executor.js';

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "rtk-for-dsh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DeepSeek Harness bash executor that routes commands through RTK (rtk rewrite)",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./sandbox": {
+      "types": "./lib/sandbox.d.ts",
+      "default": "./lib/sandbox.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node scripts/typecheck-dsh.mjs",
+    "test": "node --test src/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-bash-local": "*",
+    "@deepseek-ai/dsh-shell": "*",
+    "@deepseek-ai/schemastery": "*",
+    "@deepseek-ai/dsh-bash-sandbox": "*"
+  },
+  "license": "MIT",
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-bash-local": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-shell": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-bash-sandbox": {
+      "optional": true
+    }
+  },
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  }
+}