@try-works/dsh-righthand 0.1.0

package/lib/secrets-tools.js

@@ -0,0 +1,132 @@
+/**
+ * secrets-tools — DSH-native tools over ctx.credentials + ctx.settings.
+ * The righthand plugin's auth surface: declare a credential reference,
+ * describe it (never the value), set/unset through the provider, and read
+ * plugin settings from a registered namespace (redacted).
+ * Built on the harness's own seams, not a hand-rolled secret store.
+ * @module dsh-righthand/secrets-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+export const name = 'righthand-secrets';
+export const inject = ['tools', 'credentials', 'settings'];
+export const righthandSettingsSchema = z.object({
+    accountId: z.string().default(''),
+    defaultScriptPrefix: z.string().default('rh-'),
+    defaultZone: z.string().default(''),
+});
+/** Register the settings namespace + the secret/credential tools. */
+export function apply(ctx) {
+    const ns = settingsNamespace('righthand');
+    // Register once; the settings provider merges schema defaults + user doc.
+    const scope = ctx.settings.register(ns, righthandSettingsSchema);
+    ctx.tools.register(defineTool({
+        name: 'rh_credential_describe',
+        description: 'Report whether a credential reference is configured (and from which source layer), without ever returning the secret value. Use this to check auth state before a deploy/invoke.',
+        parameters: {
+            ref: { type: 'string', required: true, description: 'Credential reference, e.g. CLOUDFLARE_API_TOKEN.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ref: { type: 'string', required: true },
+                    configured: { type: 'boolean', required: true },
+                    source: { type: 'string' },
+                    writable: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `${value.ref}: configured=${value.configured}${value.source ? ' (source=' + value.source + ')' : ''}, writable=${value.writable}` }],
+        },
+        async execute(args) {
+            const ref = credentialRef(args.ref);
+            const info = await ctx.credentials.describe(ref);
+            return { ref: args.ref, configured: info.configured, ...info.source !== undefined ? { source: info.source } : {}, writable: info.writable };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_credential_set',
+        description: 'Store a secret value for a credential reference through the harness credential provider. The value is written durably and never echoed back.',
+        parameters: {
+            ref: { type: 'string', required: true, description: 'Credential reference to store, e.g. CLOUDFLARE_API_TOKEN.' },
+            value: { type: 'string', required: true, description: 'The non-empty secret value to store.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ref: { type: 'string', required: true },
+                    stored: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `stored credential ${value.ref} (value not echoed)` }],
+        },
+        async execute(args) {
+            if (args.value.length === 0)
+                throw new Error('credential value must be non-empty');
+            await ctx.credentials.set(credentialRef(args.ref), args.value);
+            return { ref: args.ref, stored: true };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_credential_unset',
+        description: 'Remove a credential reference. Idempotent.',
+        parameters: {
+            ref: { type: 'string', required: true, description: 'Credential reference to remove.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ref: { type: 'string', required: true },
+                    removed: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `removed credential ${value.ref}` }],
+        },
+        async execute(args) {
+            await ctx.credentials.unset(credentialRef(args.ref));
+            return { ref: args.ref, removed: true };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_settings_get',
+        description: 'Read the resolved righthand plugin settings (schema defaults + user overrides). Secret fields are redacted; use this to see effective account/zone/prefix configuration.',
+        parameters: {},
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute() {
+            const v = scope.get();
+            return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_settings_set',
+        description: 'Merge a partial patch into the righthand settings namespace (persisted by the harness settings provider).',
+        parameters: {
+            patch: { type: 'object', additionalProperties: true, required: true, description: 'Partial settings patch, e.g. { "accountId": "..." }.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    applied: { type: 'boolean', required: true },
+                },
+            },
+            render: () => [{ type: 'text', text: 'settings updated' }],
+        },
+        async execute(args) {
+            await scope.update(args.patch);
+            return { applied: true };
+        },
+    }));
+}
+//# sourceMappingURL=secrets-tools.js.map

package/lib/secrets-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets-tools.js","sourceRoot":"","sources":["../src/secrets-tools.ts"],"names":[],"mappings":"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"}

package/lib/store-tools.d.ts

@@ -0,0 +1,52 @@
+/**
+ * store-tools — DSH-native tools over ctx.storageDomain (domain KV).
+ * A generic, schema-validated key-value store surface the righthand plugin
+ * can reuse for its tool catalog, plus any other plugin needing durable state.
+ * Built on the harness's own storage domain facility, not a hand-rolled file.
+ * @module dsh-righthand/store-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Domain } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+export declare const name = "righthand-store";
+export declare const inject: string[];
+/** A value that JSON.stringify can carry (objects, arrays, scalars — no functions/symbols). */
+export type JsonLike = unknown;
+/** One stored record: a string key → JSON value, with a write timestamp. */
+export interface StoreRow {
+    value: JsonLike;
+    updatedAt: string;
+}
+/** Domain spec: the catalog table + a global singleton (write counter). */
+export declare const storeDomain: {
+    name: string;
+    version: number;
+    tables: {
+        rows: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            value: unknown;
+            updatedAt: string;
+        }>;
+    };
+    global: {
+        schema: z.ZodObject<{
+            writes: z.ZodNumber;
+        }, z.core.$strip>;
+        initial: {
+            writes: number;
+        };
+    };
+};
+export type StoreDomain = Domain<typeof storeDomain>;
+/** Persisted store with typed read/write over the domain tables. */
+export declare class KeyValueStore {
+    private readonly domain;
+    constructor(domain: StoreDomain);
+    get(key: string): Promise<StoreRow | undefined>;
+    put(key: string, value: JsonLike): Promise<StoreRow>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<string[]>;
+    writes(): Promise<number>;
+}
+/** Open the store on the mounted domain facility and register the model-facing tools. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=store-tools.d.ts.map

package/lib/store-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-tools.d.ts","sourceRoot":"","sources":["../src/store-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAA;AAC7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,IAAI,oBAAoB,CAAA;AACrC,eAAO,MAAM,MAAM,UAA6B,CAAA;AAEhD,+FAA+F;AAC/F,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAA;AAE9B,4EAA4E;AAC5E,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,2EAA2E;AAC3E,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;CAatB,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAA;AAEpD,oEAAoE;AACpE,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,WAAW;IAE1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAI/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIzB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAGhC;AAED,yFAAyF;AACzF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA6GxC"}

package/lib/store-tools.js

@@ -0,0 +1,163 @@
+/**
+ * store-tools — DSH-native tools over ctx.storageDomain (domain KV).
+ * A generic, schema-validated key-value store surface the righthand plugin
+ * can reuse for its tool catalog, plus any other plugin needing durable state.
+ * Built on the harness's own storage domain facility, not a hand-rolled file.
+ * @module dsh-righthand/store-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+export const name = 'righthand-store';
+export const inject = ['tools', 'storageDomain'];
+/** Domain spec: the catalog table + a global singleton (write counter). */
+export const storeDomain = defineDomain({
+    name: 'righthand_store',
+    version: 1,
+    tables: {
+        rows: domainTable(z.object({
+            value: z.unknown(),
+            updatedAt: z.string(),
+        })),
+    },
+    global: {
+        schema: z.object({ writes: z.number() }),
+        initial: { writes: 0 },
+    },
+});
+/** Persisted store with typed read/write over the domain tables. */
+export class KeyValueStore {
+    domain;
+    constructor(domain) {
+        this.domain = domain;
+    }
+    async get(key) {
+        return this.domain.table('rows').get(key);
+    }
+    async put(key, value) {
+        const row = { value, updatedAt: new Date().toISOString() };
+        await this.domain.table('rows').put(key, row);
+        const writes = this.domain.global.get();
+        await this.domain.global.set({ writes: writes.writes + 1 });
+        return row;
+    }
+    async delete(key) {
+        return this.domain.table('rows').delete(key);
+    }
+    async list() {
+        return [...this.domain.table('rows').keys()];
+    }
+    async writes() {
+        return this.domain.global.get().writes;
+    }
+}
+/** Open the store on the mounted domain facility and register the model-facing tools. */
+export function apply(ctx) {
+    let store;
+    let ready;
+    // Open the domain asynchronously (the facility may still be activating).
+    ctx.effect(() => {
+        ready = (async () => {
+            const domain = await ctx.storageDomain.open(storeDomain);
+            store = new KeyValueStore(domain);
+        })();
+        return () => { };
+    });
+    const ensure = async () => {
+        if (store === undefined) {
+            await ready;
+        }
+        if (store === undefined)
+            throw new Error('righthand store is not open (storageDomain not mounted)');
+        return store;
+    };
+    ctx.tools.register(defineTool({
+        name: 'rh_store_put',
+        description: 'Durably store a JSON value under a string key in the righthand KV store. Returns the stored record with a timestamp.',
+        parameters: {
+            key: { type: 'string', required: true, description: 'String key for the record.' },
+            value: { type: 'json', required: true, description: 'Any JSON value to store (object, array, string, number, boolean, null).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    key: { type: 'string', required: true },
+                    updatedAt: { type: 'string', required: true },
+                    writes: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `stored ${value.key} (writes=${value.writes})` }],
+        },
+        async execute(args) {
+            const s = await ensure();
+            const row = await s.put(args.key, args.value);
+            return { key: args.key, updatedAt: row.updatedAt, writes: await s.writes() };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_store_get',
+        description: 'Read a stored JSON value by key. Returns null when the key is absent.',
+        parameters: {
+            key: { type: 'string', required: true, description: 'String key to read.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    found: { type: 'boolean', required: true },
+                    key: { type: 'string', required: true },
+                    value: { type: 'json' },
+                    updatedAt: { type: 'string' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.found ? `${value.key} = ${JSON.stringify(value.value)}` : `${value.key} (absent)` }],
+        },
+        async execute(args) {
+            const s = await ensure();
+            const row = await s.get(args.key);
+            if (row === undefined)
+                return { found: false, key: args.key };
+            return { found: true, key: args.key, value: row.value, updatedAt: row.updatedAt };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_store_delete',
+        description: 'Delete a stored record by key. Returns whether it existed.',
+        parameters: {
+            key: { type: 'string', required: true, description: 'String key to delete.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    key: { type: 'string', required: true },
+                    existed: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: `deleted ${value.key}: ${value.existed}` }],
+        },
+        async execute(args) {
+            const s = await ensure();
+            const existed = await s.delete(args.key);
+            return { key: args.key, existed };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_store_list',
+        description: 'List all keys currently in the righthand KV store.',
+        parameters: {},
+        output: {
+            schema: { type: 'array', items: { type: 'string' } },
+            render: (_args, keys) => [{ type: 'text', text: keys.length === 0 ? '(empty)' : keys.join('\n') }],
+        },
+        async execute() {
+            const s = await ensure();
+            return s.list();
+        },
+    }));
+}
+//# sourceMappingURL=store-tools.js.map

package/lib/store-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-tools.js","sourceRoot":"","sources":["../src/store-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@try-works/dsh-righthand",
+  "description": "DeepSeek Harness plugin: DSH-native righthand tools — durable KV store, credential/settings management, governed exec, and a tool guard",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-jobs": "^0.1.0-rc.5",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "file:D:/deepseek-harness/vendor/cordis",
+    "@deepseek-ai/cosmokit": "file:D:/deepseek-harness/vendor/cosmokit",
+    "@deepseek-ai/schemastery": "file:D:/deepseek-harness/vendor/schemastery",
+    "@deepseek-ai/dsh-tools": "file:D:/deepseek-harness/packages/core/tools",
+    "@deepseek-ai/dsh-system-prompt": "file:D:/deepseek-harness/packages/core/system-prompt",
+    "@deepseek-ai/dsh-storage": "file:D:/deepseek-harness/packages/storage/storage",
+    "@deepseek-ai/dsh-storage-json": "file:D:/deepseek-harness/packages/storage/storage-json",
+    "@deepseek-ai/dsh-storage-domain": "file:D:/deepseek-harness/packages/storage/storage-domain",
+    "@deepseek-ai/dsh-credentials": "file:D:/deepseek-harness/packages/credentials/credentials",
+    "@deepseek-ai/dsh-settings": "file:D:/deepseek-harness/packages/settings/settings",
+    "@deepseek-ai/dsh-jobs": "file:D:/deepseek-harness/packages/jobs/jobs",
+    "@deepseek-ai/dsh-jobs-local": "file:D:/deepseek-harness/packages/jobs/jobs-local",
+    "@deepseek-ai/dsh-subprocess": "file:D:/deepseek-harness/packages/subprocess/subprocess",
+    "@deepseek-ai/dsh-subprocess-local": "file:D:/deepseek-harness/packages/subprocess/subprocess-local",
+    "@deepseek-ai/dsh-llm": "file:D:/deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-agent": "file:D:/deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-scope": "file:D:/deepseek-harness/packages/core/scope",
+    "@deepseek-ai/dsh-session": "file:D:/deepseek-harness/packages/core/session",
+    "@deepseek-ai/dsh-invariants": "file:D:/deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-user-approval": "file:D:/deepseek-harness/packages/interaction/user-approval",
+    "@deepseek-ai/dsh-brand": "file:D:/deepseek-harness/packages/util/brand",
+    "@deepseek-ai/dsh-timeout": "file:D:/deepseek-harness/packages/util/timeout",
+    "@deepseek-ai/dsh-typert-protocol": "file:D:/deepseek-harness/packages/typert/protocol",
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0",
+    "vitest": "^2.1.0",
+    "@types/node": "^20.0.0",
+    "zod": "^4.4.3",
+    "@deepseek-ai/dsh-credentials-local": "file:D:/deepseek-harness/packages/credentials/credentials-local",
+    "@deepseek-ai/dsh-settings-file": "file:D:/deepseek-harness/packages/settings/settings-file",
+    "@deepseek-ai/dsh-atomic-write": "file:D:/deepseek-harness/packages/util/atomic-write",
+    "@deepseek-ai/dsh-home-paths": "file:D:/deepseek-harness/packages/util/home-paths",
+    "@deepseek-ai/dsh-launch-environment": "file:D:/deepseek-harness/packages/util/launch-environment",
+    "@deepseek-ai/dsh-code-runtime": "file:D:/deepseek-harness/packages/code-runtime/code-runtime",
+    "@deepseek-ai/dsh-attachment": "file:D:/deepseek-harness/packages/attachment/attachment",
+    "@deepseek-ai/dsh-commands": "file:D:/deepseek-harness/packages/interaction/commands",
+    "@deepseek-ai/dsh-skill": "file:D:/deepseek-harness/packages/skill/skill"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/try-works/dsh-righthand.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/src/LEARNINGS.md

@@ -0,0 +1,39 @@
+# DSH-native tools — learnings log
+
+> Self-built tools on the harness's OWN services, verified by mounting the real providers and invoking each tool's `execute()` path. Not read-verified — executed.
+
+## What I built (all in `src/`)
+
+| Module | Tools | Native service it wraps |
+|---|---|---|
+| `store-tools.ts` | `rh_store_put/get/delete/list` | `ctx.storageDomain` (domain KV: table + global counter) |
+| `secrets-tools.ts` | `rh_credential_describe/set/unset`, `rh_settings_get/set` | `ctx.credentials` + `ctx.settings` |
+| `exec-tools.ts` | `rh_run`, `rh_run_bg` | `ctx.subprocess` + `ctx.jobs` |
+| `guard-tools.ts` | (policy, not a tool) | `ctx.tools` `tools/pre-execute` |
+
+## Test results (mine — `tests/dsh-native-tools.spec.ts`, 7/7 pass)
+
+Booted a real `Context` with: `SystemPrompt` + `ToolRuntime` + `Storage` hub + `storage-json` + `storage-domain` + `credentials-local` + `settings-file` + `jobs-local` + `subprocess-local`, then mounted each tool plugin and called `ctx.tools.execute(...)`.
+
+1. `rh_store_put/get/delete/list` round-trips a JSON value durably through the domain KV.
+2. The domain's **global singleton** increments a write counter across puts (writes=1 then writes=2).
+3. `rh_credential_set` stores a secret; `rh_credential_describe` reports `configured` + source WITHOUT the value (asserted the secret string never appears in any output).
+4. `rh_settings_get` returns schema defaults (`rh-` prefix); `rh_settings_set` merges a patch and re-reads it.
+5. `rh_run` runs `node --version` → exit 0 + stdout matching `/v\d+/`.
+6. `rh_run_bg` starts a `ctx.jobs` background job that settles `completed`.
+7. `guard-tools` denies a `rh_deny_` tool through `tools/pre-execute` (result `isError: true`).
+
+## Learnings during build (mine — where the harness corrected my notes)
+
+1. **The real `ctx.storage` is a storage HUB, not `ctx.storage.sql`.** My §9.2 notes said `ctx.storage.sql` (that is the Cloudflare DO's storage, not the harness). The harness `ctx.storage` exposes named backends (`backend.register('json', ...)`) with a `kv` facet; the ergonomic layer is `ctx.storageDomain` → `defineDomain` + `domain.table('rows').put/get/delete/keys()` + `domain.global.get()/set()`. Records are validated by **zod** (not schemastery) at the durable-read boundary.
+2. **`domain.table(name)` returns a handle; there is no `domain.tables.<name>` object.** And the table verb is `put`, not `set`. My first pass guessed the API and the execute() returned `Cannot read properties of undefined (reading 'set')` — the real API corrected it.
+3. **`ctx.jobs.start` refuses until a controller is attached** (`attachController('name')`), exactly like `tool-jobs`. My first `rh_run_bg` would have been rejected without it.
+4. **`ctx.plugin()` accepts function/class/`{apply}` plugins uniformly**, and `Service` subclasses (`LocalCredentialProvider`, `FileSettingsProvider`, `LocalJobRegistry`, `Storage`, `ToolRuntime`, `SystemPrompt`) are directly pluggable — the `file:` devDeps + pnpm `overrides`/`linkWorkspacePackages` recipe (from `dsh-paper-design`) is the right way to test against the real runtime.
+5. **`tools/pre-execute` with `{prepend: true}` + a throw is the clean deny gate** — the tool never dispatches and the result is `isError`. No wrapper needed.
+6. **Cordis Contexts cannot have arbitrary properties set on them** (`cannot set property without provide`). Observability must go through a real service/`provide`, not a monkey-patched field.
+7. **Subprocess env scrubbing is built in**: the seam exports `scrubbedParentEnv()` (strips `KEY/PASSWORD/SECRET/TOKEN` + `DSH_*`), so a plugin spawning a CLI gets secret hygiene for free.
+
+## Fits dsh-righthand as
+
+- These are the **generic DSH-native primitives** the Cloudflare tools will build on: the durable tool catalog is `rh_store_*` over `storageDomain`; auth is `rh_credential_*`; deploy/invoke is `rh_run`/`rh_run_bg` over subprocess+jobs; high-impact gates are `guard-tools`.
+- The **test harness** (`tests/dsh-native-tools.spec.ts`) is the reusable mount pattern for every future tool module.

package/src/exec-tools.ts

@@ -0,0 +1,121 @@
+/**
+ * exec-tools — DSH-native tools over ctx.subprocess + ctx.jobs.
+ * A governed "run a command" surface: rh_run (foreground collect) and
+ * rh_run_bg (background job via ctx.jobs). Built on the harness's own
+ * subprocess and job services, so cancellation + tree-scoped termination
+ * + ownership come from the harness, not a hand-rolled child_process.
+ * @module dsh-righthand/exec-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type {} from '@deepseek-ai/dsh-jobs'
+
+export const name = 'righthand-exec'
+export const inject = ['tools', 'subprocess', 'jobs']
+
+/** Run a command and collect bounded output; returns exit facts + tail. */
+export function apply(ctx: Context): void {
+  // Producers may start work only while a controller is attached (tool-jobs pattern).
+  ctx.jobs.attachController('righthand-exec')
+  ctx.tools.register(defineTool({
+    name: 'rh_run',
+    description: 'Run a single command (argv array, no shell interpretation) in collect mode and return exit facts plus bounded stdout/stderr tail. Cancellation is tree-scoped by the harness subprocess service.',
+    parameters: {
+      argv: { type: 'array', required: true, items: { type: 'string' }, description: 'Full argv; argv[0] is the executable (e.g. ["node","--version"]).' },
+      cwd: { type: 'string', description: 'Working directory (defaults to process.cwd()).' },
+      maxOutputBytes: { type: 'integer', description: 'Per-stream in-memory cap (default 4096).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          exitCode: { type: 'number' },
+          signal: { type: 'string' },
+          stdout: { type: 'string', required: true },
+          stderr: { type: 'string', required: true },
+          stdoutTruncated: { type: 'boolean', required: true },
+          stderrTruncated: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `exit ${value.exitCode ?? ('signal ' + value.signal)}; stdout=${value.stdout.length}b stderr=${value.stderr.length}b` }],
+    },
+    async execute(args, exec) {
+      const maxBytes = args.maxOutputBytes ?? 4096
+      const spec: SubprocessSpawnSpec = {
+        argv: args.argv,
+        cwd: args.cwd ?? process.cwd(),
+        stdio: {
+          stdin: 'ignore',
+          stdout: { maxBytes },
+          stderr: { maxBytes },
+        },
+        graceMs: 5000,
+        signal: exec.signal,
+      }
+      const handle = ctx.subprocess.spawn(spec)
+      const outcome = await handle.done
+      const so = handle.collected.stdout?.readFrom(0)
+      const se = handle.collected.stderr?.readFrom(0)
+      return {
+        exitCode: outcome.exitCode ?? undefined,
+        ...outcome.signal !== null ? { signal: String(outcome.signal) } : {},
+        stdout: so?.text ?? '',
+        stderr: se?.text ?? '',
+        stdoutTruncated: so?.lossy ?? false,
+        stderrTruncated: se?.lossy ?? false,
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_run_bg',
+    description: 'Start a command as a background job (owner-scoped, cancellable via the harness job registry). Returns the job id; read it back with the job_output-style flow or the registry.',
+    parameters: {
+      argv: { type: 'array', required: true, items: { type: 'string' }, description: 'Full argv; argv[0] is the executable.' },
+      cwd: { type: 'string', description: 'Working directory (defaults to process.cwd()).' },
+      label: { type: 'string', description: 'Short human-readable label for the job.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          jobId: { type: 'string', required: true },
+          label: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `started background job ${value.jobId} (${value.label})` }],
+    },
+    async execute(args, exec) {
+      const label = args.label ?? args.argv.join(' ')
+      const jobId = ctx.jobs.start({
+        kind: 'bash' as any,
+        label,
+        owner: exec.agent,
+        run() {
+          const handle = ctx.subprocess.spawn({
+            argv: args.argv,
+            cwd: args.cwd ?? process.cwd(),
+            stdio: { stdin: 'ignore', stdout: { maxBytes: 8192 }, stderr: { maxBytes: 8192 } },
+            graceMs: 5000,
+          })
+          return {
+            cancel(reason) { handle.terminate() },
+            done: (async () => {
+              const outcome = await handle.done
+              const so = handle.collected.stdout?.readFrom(0)
+              const se = handle.collected.stderr?.readFrom(0)
+              if (outcome.exitCode === 0) return { status: 'completed' as const, detail: `exit 0`, output: so?.text ?? '' }
+              return { status: 'failed' as const, detail: `exit ${outcome.exitCode}`, output: (se?.text ?? '') || (so?.text ?? '') }
+            })(),
+            readOutput() { return '' },
+          }
+        },
+      })
+      return { jobId: String(jobId), label }
+    },
+  }))
+}