dsh-harbor-evolution 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 istarwyh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# dsh-harbor-evolution
+
+Cordis bundle for evaluating immutable DeepSeek Harness Candidates with Harbor.
+
+## Install
+
+Install `harbor-dsh-evolution` into the same Python environment as Harbor, then add this bundle to the DSH profile:
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python harbor-dsh-evolution
+source .venv/bin/activate
+pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add dsh-harbor-evolution
+```
+
+For development from this repository:
+
+```bash
+./hse dsh-install headless
+```
+
+`-w` is required by pnpm when the DSH profile directory is its workspace root.
+
+The bundle inserts one `harbor-evolution` entry and registers four model-facing tools:
+
+- `harbor_candidate_snapshot`
+- `harbor_eval_run`
+- `harbor_eval_result`
+- `harbor_candidate_compare`
+
+The shortest evaluation call needs only `candidatePath` and `datasetPath`. Candidate identity defaults to `package.json`, the Job name is generated automatically, and `harbor_eval_run` returns the completed evaluation summary directly.
+
+The helper launches a fixed DSH version through `pnpm dlx`, so it does not conflict with a long-running `npx` DSH process. When installed from this monorepo, the bundle automatically discovers the sibling Python virtual environment created by `./hse dsh-install`. Otherwise it uses `HARBOR_BIN` / `HARBOR_DSH_BIN`, then falls back to `PATH`. Override the inserted entry in the profile's `cordis.patch.yml` when the binaries or Python source live elsewhere:
+
+```yaml
+- id: harbor-evolution
+  config:
+    projectRoot: /workspace/my-agent
+    jobsDir: jobs
+    harborBin: /workspace/venv/bin/harbor
+    harborDshBin: /workspace/venv/bin/harbor-dsh
+    pythonPath: /workspace/harbor-self-evolving/packages/harbor-plugin/src
+```
+
+This replaces the complete config for the entry, following DSH patch semantics.
+
+The plugin never mutates the active DSH profile and never deploys a Candidate. Another system updates the Champion only after the external Promotion Gate passes.

package/bin/dsh-harbor.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { snapshotCandidate } from '../lib/candidate.js'
+import { runProcess } from '../lib/process.js'
+
+function usage() {
+  console.error('Usage: dsh-harbor snapshot <candidate-dir> [--id <id>] [--version <version>]')
+  console.error('       dsh-harbor doctor')
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2)
+  if (command === 'doctor') {
+    const harbor = await runProcess(process.env.HARBOR_BIN || 'harbor', ['--version'], { timeoutMs: 10000 })
+    const plugins = await runProcess(process.env.HARBOR_BIN || 'harbor', ['plugins', 'list'], { timeoutMs: 10000 })
+    console.log(JSON.stringify({ harbor: harbor.stdout.trim(), plugins: plugins.stdout.trim() }, null, 2))
+    return
+  }
+  if (command === 'snapshot') {
+    const candidateDir = args.shift()
+    const idIndex = args.indexOf('--id')
+    const versionIndex = args.indexOf('--version')
+    if (!candidateDir) throw new Error('snapshot requires candidate-dir')
+    const manifest = await snapshotCandidate(candidateDir, {
+      candidateId: idIndex < 0 ? undefined : args[idIndex + 1],
+      version: versionIndex < 0 ? undefined : args[versionIndex + 1],
+    })
+    console.log(JSON.stringify(manifest, null, 2))
+    return
+  }
+  usage()
+  process.exitCode = 2
+}
+
+main().catch(error => {
+  console.error(error.message)
+  process.exitCode = 1
+})

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: harbor-evolution
+      name: dsh-harbor-evolution

package/index.js

@@ -0,0 +1,97 @@
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { compareCandidates, readEvaluation, runEvaluation, snapshot } from './lib/evolution.js'
+
+export const name = 'harbor-evolution'
+export const inject = ['tools']
+
+const packageDir = path.dirname(fileURLToPath(import.meta.url))
+const checkoutPythonPackage = path.resolve(packageDir, '../harbor-plugin')
+
+function checkoutExecutable(name) {
+  const candidate = path.join(checkoutPythonPackage, '.venv', 'bin', name)
+  return existsSync(candidate) ? candidate : name
+}
+
+export const Config = Schema.object({
+  projectRoot: Schema.string().default('.'),
+  jobsDir: Schema.string().default('jobs'),
+  harborBin: Schema.string().default(''),
+  harborDshBin: Schema.string().default(''),
+  dshVersion: Schema.string().default('0.1.0-rc.6'),
+  agentImportPath: Schema.string().default('harbor_dsh_evolution.agent:DshCandidateAgent'),
+  pluginImportPath: Schema.string().default('dsh-evolution'),
+  pythonPath: Schema.string().default(''),
+  timeoutMs: Schema.number().default(1800000),
+})
+
+function jsonTool(definition, execute) {
+  return defineTool({
+    ...definition,
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      return JSON.stringify(await execute(args), null, 2)
+    },
+  })
+}
+
+export function apply(ctx, config) {
+  const resolved = {
+    ...config,
+    projectRoot: path.resolve(config.projectRoot),
+    harborBin: config.harborBin || process.env.HARBOR_BIN || checkoutExecutable('harbor'),
+    harborDshBin: config.harborDshBin || process.env.HARBOR_DSH_BIN || checkoutExecutable('harbor-dsh'),
+    pythonPath: config.pythonPath || (
+      existsSync(path.join(checkoutPythonPackage, 'src'))
+        ? path.join(checkoutPythonPackage, 'src')
+        : ''
+    ),
+  }
+
+  ctx.tools.register(jsonTool({
+    name: 'harbor_candidate_snapshot',
+    description: 'Freeze a DeepSeek Harness Cordis composition as an immutable Candidate manifest. Candidate id and version default to package.json.',
+    parameters: {
+      candidatePath: { type: 'string', required: true },
+      candidateId: { type: 'string' },
+      version: { type: 'string' },
+    },
+  }, args => snapshot(resolved, args)))
+
+  ctx.tools.register(jsonTool({
+    name: 'harbor_eval_run',
+    description: 'Snapshot and run one DeepSeek Harness Candidate against a Harbor dataset, then return the completed evaluation summary.',
+    parameters: {
+      candidatePath: { type: 'string', required: true },
+      candidateId: { type: 'string' },
+      version: { type: 'string' },
+      datasetPath: { type: 'string', required: true },
+      jobName: { type: 'string' },
+    },
+  }, args => runEvaluation(resolved, args)))
+
+  ctx.tools.register(jsonTool({
+    name: 'harbor_eval_result',
+    description: 'Read the stable evaluation summary produced for a Harbor Job.',
+    parameters: {
+      jobPath: { type: 'string', required: true },
+    },
+  }, args => readEvaluation(resolved, args)))
+
+  ctx.tools.register(jsonTool({
+    name: 'harbor_candidate_compare',
+    description: 'Apply the deterministic Promotion Gate to a baseline Job and a Candidate Job.',
+    parameters: {
+      baselineJob: { type: 'string', required: true },
+      candidateJob: { type: 'string', required: true },
+      policyPath: { type: 'string', required: true },
+    },
+  }, args => compareCandidates(resolved, args)))
+}

package/lib/candidate.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+export const MANIFEST_NAME = 'candidate-manifest.json'
+const DIGEST_PREFIX = Buffer.from('harbor-dsh-candidate-v1\0')
+const EXCLUDED_DIRS = new Set(['.git', 'node_modules', '__pycache__'])
+const EXCLUDED_FILES = new Set([MANIFEST_NAME, '.DS_Store'])
+
+async function walk(root, current = root) {
+  const entries = await readdir(current, { withFileTypes: true })
+  const files = []
+  for (const entry of entries) {
+    const absolute = path.join(current, entry.name)
+    const relative = path.relative(root, absolute).split(path.sep).join('/')
+    if (entry.isSymbolicLink()) throw new Error(`Candidate must not contain symlinks: ${relative}`)
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DIRS.has(entry.name)) files.push(...await walk(root, absolute))
+    } else if (entry.isFile() && !EXCLUDED_FILES.has(entry.name)) {
+      files.push({ absolute, relative })
+    }
+  }
+  return files.sort((a, b) => Buffer.compare(Buffer.from(a.relative), Buffer.from(b.relative)))
+}
+
+export async function computeCandidate(candidateDir) {
+  const root = path.resolve(candidateDir)
+  if (!(await stat(root)).isDirectory()) throw new Error(`Candidate path is not a directory: ${root}`)
+  const digest = createHash('sha256')
+  digest.update(DIGEST_PREFIX)
+  const files = []
+  for (const item of await walk(root)) {
+    const content = await readFile(item.absolute)
+    files.push({
+      path: item.relative,
+      size: content.length,
+      sha256: createHash('sha256').update(content).digest('hex'),
+    })
+    digest.update(item.relative)
+    digest.update('\0')
+    digest.update(String(content.length))
+    digest.update('\0')
+    digest.update(content)
+    digest.update('\0')
+  }
+  return { digest: `sha256:${digest.digest('hex')}`, files }
+}
+
+export async function snapshotCandidate(candidateDir, options = {}) {
+  const root = path.resolve(candidateDir)
+  for (const required of ['cordis.yml', 'package.json']) {
+    try {
+      if (!(await stat(path.join(root, required))).isFile()) throw new Error()
+    } catch {
+      throw new Error(`Candidate is missing required file: ${required}`)
+    }
+  }
+  let packageJson
+  try {
+    packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'))
+  } catch (error) {
+    throw new Error(`Candidate package.json is not valid JSON: ${error.message}`)
+  }
+  const candidateId = options.candidateId ?? packageJson.name
+  const version = options.version ?? packageJson.version
+  const runtimeVersion = options.runtimeVersion ?? '0.1.0-rc.6'
+  if (!candidateId || !version || !runtimeVersion) {
+    throw new Error('Candidate id, version, and runtime version must not be empty; set package.json name/version or pass explicit values')
+  }
+  const computed = await computeCandidate(root)
+  const manifest = {
+    schema_version: 1,
+    candidate_id: String(candidateId),
+    version: String(version),
+    digest: computed.digest,
+    created_at: new Date().toISOString(),
+    runtime: {
+      kind: 'deepseek-harness',
+      version: String(runtimeVersion),
+      transport: 'acp',
+    },
+    files: computed.files,
+    metadata: options.metadata ?? {},
+  }
+  await mkdir(root, { recursive: true })
+  await writeFile(path.join(root, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}\n`)
+  return manifest
+}

package/lib/evolution.js

@@ -0,0 +1,88 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { MANIFEST_NAME, snapshotCandidate } from './candidate.js'
+import { runProcess } from './process.js'
+
+export function resolveWithin(root, value, label) {
+  const base = path.resolve(root)
+  const resolved = path.resolve(base, value)
+  if (resolved !== base && !resolved.startsWith(`${base}${path.sep}`)) {
+    throw new Error(`${label} must stay under projectRoot`)
+  }
+  return resolved
+}
+
+export async function snapshot(config, args) {
+  const candidateDir = resolveWithin(config.projectRoot, args.candidatePath, 'candidatePath')
+  return snapshotCandidate(candidateDir, {
+    candidateId: args.candidateId,
+    version: args.version,
+    runtimeVersion: config.dshVersion,
+  })
+}
+
+function slug(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+|[._-]+$/g, '') || 'candidate'
+}
+
+export function makeJobName(manifest, now = new Date()) {
+  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[-:]/g, '')
+  const suffix = `${timestamp}-${manifest.digest.slice(7, 15)}`
+  const available = 100 - suffix.length - 1
+  const identity = `${slug(manifest.candidate_id)}-${slug(manifest.version)}`.slice(0, available)
+  return `${identity}-${suffix}`
+}
+
+export async function runEvaluation(config, args) {
+  const manifest = await snapshot(config, args)
+  const candidateDir = resolveWithin(config.projectRoot, args.candidatePath, 'candidatePath')
+  const dataset = resolveWithin(config.projectRoot, args.datasetPath, 'datasetPath')
+  const jobsDir = resolveWithin(config.projectRoot, config.jobsDir, 'jobsDir')
+  const jobName = args.jobName ?? makeJobName(manifest)
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(jobName)) throw new Error('jobName contains unsupported characters')
+
+  const harborArgs = [
+    'run', '-p', dataset,
+    '-a', config.agentImportPath,
+    '--ak', `candidate_path=${candidateDir}`,
+    '--ak', `candidate_version=${manifest.version}`,
+    '--ak', `candidate_digest=${manifest.digest}`,
+    '--job-name', jobName,
+    '--jobs-dir', jobsDir,
+    '--plugin', config.pluginImportPath,
+    '--plugin-kwarg', `candidate_manifest=${path.join(candidateDir, MANIFEST_NAME)}`,
+  ]
+  const result = await runProcess(config.harborBin, harborArgs, {
+    cwd: config.projectRoot,
+    timeoutMs: config.timeoutMs,
+    env: { ...process.env, ...(config.pythonPath ? { PYTHONPATH: config.pythonPath } : {}) },
+  })
+  const jobDir = path.join(jobsDir, jobName)
+  const summary = JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))
+  return { manifest, jobDir, summary, process: { code: result.code } }
+}
+
+export async function readEvaluation(config, args) {
+  const jobDir = resolveWithin(config.projectRoot, args.jobPath, 'jobPath')
+  return JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))
+}
+
+export async function compareCandidates(config, args) {
+  const baseline = resolveWithin(config.projectRoot, args.baselineJob, 'baselineJob')
+  const candidate = resolveWithin(config.projectRoot, args.candidateJob, 'candidateJob')
+  const policy = resolveWithin(config.projectRoot, args.policyPath, 'policyPath')
+  const result = await runProcess(config.harborDshBin, [
+    'promote', baseline, candidate, '--policy', policy,
+  ], {
+    cwd: config.projectRoot,
+    timeoutMs: config.timeoutMs,
+    // harbor-dsh uses exit 1 for a valid REJECT decision. The report remains
+    // model-readable; infrastructure failures still reject the subprocess.
+    allowedExitCodes: [0, 1],
+  })
+  return JSON.parse(result.stdout)
+}

package/lib/process.js

@@ -0,0 +1,31 @@
+import { spawn } from 'node:child_process'
+
+export function runProcess(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    const timeout = setTimeout(() => {
+      child.kill('SIGTERM')
+      reject(new Error(`Command timed out after ${options.timeoutMs}ms: ${command}`))
+    }, options.timeoutMs ?? 1_800_000)
+    child.stdout.on('data', chunk => { stdout += chunk })
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.on('error', error => {
+      clearTimeout(timeout)
+      reject(error)
+    })
+    child.on('close', code => {
+      clearTimeout(timeout)
+      const result = { command, args, code, stdout, stderr }
+      const allowedExitCodes = options.allowedExitCodes ?? [0]
+      if (allowedExitCodes.includes(code)) resolve(result)
+      else reject(Object.assign(new Error(`Command failed with exit code ${code}: ${command}`), { result }))
+    })
+  })
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-harbor-evolution",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin for snapshotting Cordis Candidates and evaluating them with Harbor.",
+  "type": "module",
+  "main": "index.js",
+  "exports": "./index.js",
+  "bin": {
+    "dsh-harbor": "bin/dsh-harbor.mjs"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "bin/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check index.js && node --check bin/dsh-harbor.mjs && node --test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "harbor",
+    "agent-evaluation",
+    "agent-evolution",
+    "cordis"
+  ],
+  "homepage": "https://github.com/istarwyh/harbor-self-evolving#readme",
+  "bugs": {
+    "url": "https://github.com/istarwyh/harbor-self-evolving/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/istarwyh/harbor-self-evolving.git",
+    "directory": "packages/dsh-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}