@try-works/dsh-righthand 0.1.0

package/src/guard-tools.ts

@@ -0,0 +1,40 @@
+/**
+ * guard-tools — DSH-native policy primitive over the tools pre-execute seam.
+ * Demonstrates the §4.4 allow/deny/ask gate the righthand plugin uses to
+ * gate high-impact deploy/invoke tools. Built on ctx.on('tools/pre-execute'),
+ * not a hand-rolled wrapper.
+ * @module dsh-righthand/guard-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'righthand-guard'
+export const inject = ['tools']
+
+export interface GuardRule {
+  /** Tool name prefix to gate (e.g. 'rh_' gates every righthand tool). */
+  toolPrefix: string
+  /** 'allow' passes through; 'deny' blocks; 'ask' defers to a policy function. */
+  mode: 'allow' | 'deny' | 'ask'
+  /** Only consulted when mode is 'ask'. Return true to allow. */
+  ask?: (args: unknown) => boolean
+}
+
+/** Apply a guard over a set of tool-name prefixes. */
+export function apply(ctx: Context, config: { rules?: GuardRule[] } = {}): void {
+  const rules = config.rules ?? []
+
+  ctx.on('tools/pre-execute', (exec, next) => {
+    const rule = rules.find(r => exec.name.startsWith(r.toolPrefix))
+    if (rule === undefined) return next()
+    if (rule.mode === 'deny') {
+      throw new Error(`tool ${exec.name} is denied by righthand guard`)
+    }
+    if (rule.mode === 'ask') {
+      const allowed = rule.ask?.(exec.arguments) ?? false
+      if (!allowed) throw new Error(`tool ${exec.name} requires approval (ask returned false)`)
+      return next()
+    }
+    return next()
+  }, { prepend: true })
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * dsh-righthand — DeepSeek Harness plugin.
+ * DSH-native righthand tools: a durable KV store, credential/settings
+ * management, governed command execution, and a tool guard — all built on
+ * the harness's own services (storageDomain, credentials, settings,
+ * subprocess, jobs, tools), not hand-rolled primitives.
+ *
+ * The package's plugin entry (name/inject/apply) mounts the four tool
+ * modules as child fibers; each child waits on its own services, so a
+ * profile without `storageDomain` (e.g. headless) simply gets the other
+ * nine tools instead of failing the boot.
+ *
+ * Modules (each individually mountable via `export * as ...`):
+ * - store-tools:     rh_store_put/get/delete/list over ctx.storageDomain
+ * - secrets-tools:   rh_credential_describe/set/unset + rh_settings_get/set
+ * - exec-tools:      rh_run / rh_run_bg over ctx.subprocess + ctx.jobs
+ * - guard-tools:     tools/pre-execute policy (config.rules)
+ *
+ * @module @try-works/dsh-righthand
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import * as storeTools from './store-tools.ts'
+import * as secretsTools from './secrets-tools.ts'
+import * as execTools from './exec-tools.ts'
+import * as guardTools from './guard-tools.ts'
+import type { GuardRule } from './guard-tools.ts'
+
+export const name = 'dsh-righthand'
+
+/** The combined plugin needs no services itself; each child waits on its own. */
+export const inject: string[] = []
+
+/** Combined-plugin configuration. */
+export interface RighthandConfig {
+  /** guard-tools policy rules; omitted rules leave the guard inert. */
+  rules?: GuardRule[]
+}
+
+/**
+ * Mount the four righthand tool modules as child fibers.
+ * Each child declares its own service inject, so a profile missing one
+ * service (e.g. `storageDomain` outside the web profile) skips that family
+ * instead of failing the whole plugin.
+ */
+export function apply(ctx: Context, config: RighthandConfig = {}): void {
+  ctx.plugin(storeTools)
+  ctx.plugin(secretsTools)
+  ctx.plugin(execTools)
+  ctx.plugin(guardTools, { rules: config.rules ?? [] })
+}
+
+// Individual modules stay importable for selective mounting.
+export { storeTools, secretsTools, execTools, guardTools }
+export type { GuardRule } from './guard-tools.ts'
+

package/src/secrets-tools.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis'
+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']
+
+/** righthand plugin settings namespace schema. */
+export interface RighthandSettings {
+  accountId: string
+  defaultScriptPrefix: string
+  defaultZone: string
+}
+
+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: Context): void {
+  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 as Partial<RighthandSettings>)
+      return { applied: true }
+    },
+  }))
+}

package/src/store-tools.ts

@@ -0,0 +1,184 @@
+/**
+ * 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 { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import type { Domain } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+
+export const name = 'righthand-store'
+export const inject = ['tools', 'storageDomain']
+
+/** 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 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 },
+  },
+})
+
+export type StoreDomain = Domain<typeof storeDomain>
+
+/** Persisted store with typed read/write over the domain tables. */
+export class KeyValueStore {
+  constructor(private readonly domain: StoreDomain) {}
+
+  async get(key: string): Promise<StoreRow | undefined> {
+    return this.domain.table('rows').get(key) as StoreRow | undefined
+  }
+
+  async put(key: string, value: JsonLike): Promise<StoreRow> {
+    const row: StoreRow = { 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: string): Promise<boolean> {
+    return this.domain.table('rows').delete(key)
+  }
+
+  async list(): Promise<string[]> {
+    return [...this.domain.table('rows').keys()]
+  }
+
+  async writes(): Promise<number> {
+    return this.domain.global.get().writes
+  }
+}
+
+/** Open the store on the mounted domain facility and register the model-facing tools. */
+export function apply(ctx: Context): void {
+  let store: KeyValueStore | undefined
+  let ready: Promise<void> | undefined
+
+  // 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 () => { /* domain facility owns the domain; closing happens at unmount */ }
+  })
+
+  const ensure = async (): Promise<KeyValueStore> => {
+    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 as any, 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()
+    },
+  }))
+}