@pedyc/harness-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedyc
+
+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,48 @@
+# @pedyc/harness-core
+
+Technology-stack agnostic runtime primitives for Pedyc Harness. The package has no
+dependency on Vue or on any project layout, and is used by `pedyc-harness`.
+
+## API
+
+```js
+import {
+  detectPackageManager,
+  packageScriptCommand,
+  normalizeTask,
+  readTaskFile,
+  runCommand,
+  changedFiles,
+  snapshotFiles,
+  loadSchemas,
+  createValidators,
+  validationDetails,
+  parseAgentResponse,
+  validateStageResponse,
+  validatePolicy,
+  findOutOfScopeChanges,
+  isCommandAllowed,
+  createProviderRunner,
+  runOrchestrator,
+} from '@pedyc/harness-core'
+```
+
+Individual modules are also exported for narrower imports:
+
+```js
+import { detectPackageManager } from '@pedyc/harness-core/package-manager'
+import { runOrchestrator } from '@pedyc/harness-core/orchestrator'
+```
+
+- `package-manager` / `command` — lockfile detection and command execution.
+- `intake` / `schema` / `agent` — task normalization, Ajv validation and Agent
+  response parsing.
+- `policy` / `provider` / `orchestrator` — path policy, Provider routing and the
+  four-phase execution loop.
+
+`runOrchestrator({ dryRun: true })` skips every Agent Provider and verification gate
+and returns a structured passing result.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pedyc/harness-core",
+  "version": "1.0.0",
+  "description": "Runtime primitives for Pedyc Harness",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package-manager": "./src/package-manager.mjs",
+    "./intake": "./src/intake.mjs",
+    "./command": "./src/command.mjs",
+    "./snapshots": "./src/snapshots.mjs",
+    "./schema": "./src/schema.mjs",
+    "./agent": "./src/agent.mjs",
+    "./policy": "./src/policy.mjs",
+    "./provider": "./src/provider.mjs",
+    "./orchestrator": "./src/orchestrator.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedyc/pedyc-harness.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/pedyc/pedyc-harness#readme",
+  "bugs": {
+    "url": "https://github.com/pedyc/pedyc-harness/issues"
+  },
+  "keywords": [
+    "agent",
+    "harness",
+    "orchestration",
+    "runtime"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/agent.mjs

@@ -0,0 +1,27 @@
+export const parseAgentResponse = (name, stdout, validate, ajv) => {
+  const trimmed = stdout.trim()
+  if (!trimmed) return { ok: true, details: `${name} completed without a response payload.`, payload: {} }
+  try {
+    const payload = JSON.parse(trimmed)
+    if (!validate(payload)) {
+      return { ok: false, details: `${name} returned an invalid response: ${ajv.errorsText(validate.errors)}`, payload: {} }
+    }
+    return { ok: true, details: payload.details ?? `${name} returned a structured response.`, payload }
+  } catch {
+    return { ok: false, details: `${name} must return one JSON object on stdout.`, payload: {} }
+  }
+}
+
+export const validateStageResponse = (name, payload) => {
+  if (name === 'planner' && (!Array.isArray(payload.implementationPlan) || payload.implementationPlan.length === 0)) {
+    return 'planner must return a non-empty implementationPlan.'
+  }
+  if (name === 'tester') {
+    if (typeof payload.approved !== 'boolean') return 'tester must return a boolean approved field.'
+    if (!Array.isArray(payload.evidence) || payload.evidence.length === 0) return 'tester must return non-empty evidence.'
+  }
+  if (name === 'reviewer' && typeof payload.approved !== 'boolean') {
+    return 'reviewer must return a boolean approved field.'
+  }
+  return null
+}

package/src/command.mjs

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process'
+
+const normalizeCommand = (command) => {
+  if (
+    process.platform === 'win32'
+    && ['npm', 'npx', 'pnpm', 'yarn'].includes(command)
+    && !command.endsWith('.cmd')
+  ) {
+    return `${command}.cmd`
+  }
+  return command
+}
+
+export const runCommand = (root, command, args = [], stdin = null) => new Promise((resolve) => {
+  const child = spawn(normalizeCommand(command), args, {
+    cwd: root,
+    shell: process.platform === 'win32',
+    windowsHide: true,
+  })
+  let stdout = ''
+  let stderr = ''
+  child.stdout.on('data', (chunk) => { stdout += chunk })
+  child.stderr.on('data', (chunk) => { stderr += chunk })
+  child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  child.on('error', (error) => resolve({ code: 1, stdout, stderr: error.message }))
+  if (stdin !== null) child.stdin.write(`${JSON.stringify(stdin)}\n`)
+  child.stdin.end()
+})

package/src/index.mjs

@@ -0,0 +1,11 @@
+export { detectPackageManager, packageScriptCommand } from './package-manager.mjs'
+export { normalizeTask, readTaskFile } from './intake.mjs'
+export { runCommand } from './command.mjs'
+export { changedFiles, snapshotFiles } from './snapshots.mjs'
+export { loadSchemas, createValidators, validationDetails } from './schema.mjs'
+export { parseAgentResponse, validateStageResponse } from './agent.mjs'
+export { validatePolicy, findOutOfScopeChanges, isCommandAllowed } from './policy.mjs'
+export { createProviderRunner } from './provider.mjs'
+export { runOrchestrator } from './orchestrator.mjs'
+
+export const harnessCoreVersion = '1.0.0'

package/src/intake.mjs

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs'
+
+const defaultChecks = ['pnpm run harness:verify', 'pnpm run type-check', 'pnpm run test:unit', 'pnpm run build']
+
+export const normalizeTask = (task) => {
+  const normalized = {
+    feature: task.task?.trim() || task.feature?.trim() || '',
+    objective: task.goal?.trim() || task.objective?.trim() || '',
+    constraints: task.specialConstraints ?? task.constraints ?? [],
+    acceptanceCriteria: task.acceptance ?? task.acceptanceCriteria ?? [],
+    testHints: task.testHints ?? defaultChecks,
+    maxIterations: task.maxIterations ?? 3,
+  }
+  const questions = []
+  if (!normalized.feature) questions.push('要实现的任务或功能是什么？')
+  if (!normalized.objective) questions.push('任务的目标是什么？')
+  if (!normalized.acceptanceCriteria.length) questions.push('完成任务的验收标准是什么？')
+  return questions.length > 0
+    ? { status: 'needs_input', questions, normalizedTask: normalized }
+    : { status: 'ready', normalizedTask: normalized, questions: [] }
+}
+
+export const readTaskFile = (path) => normalizeTask(JSON.parse(readFileSync(path, 'utf8')))

package/src/orchestrator.mjs

@@ -0,0 +1,119 @@
+import { findOutOfScopeChanges } from './policy.mjs'
+
+export const runOrchestrator = async ({
+  input,
+  policy,
+  dryRun,
+  snapshot,
+  changedFiles,
+  runAgent,
+  runVerification,
+  writeVerification = () => {},
+}) => {
+  const maxIterations = Math.min(
+    Math.max(Number(input.maxIterations ?? policy.maxIterations ?? 3), 1),
+    policy.maxIterations ?? 3,
+  )
+  const phases = []
+  const issues = []
+  const fileChanges = []
+  const implementationPlan = [
+    `Analyze the requested feature: ${input.feature.trim()}.`,
+    `Implement the objective while satisfying ${input.acceptanceCriteria.length} acceptance criteria.`,
+    'Run configured verification gates and review the result before reporting completion.',
+  ]
+
+  if (dryRun) {
+    // A dry run is a safe preview: no Agent Provider is invoked, no verification
+    // gate is executed, and no product file can change. Report the same four
+    // phases so callers can consume the result with the regular output contract.
+    for (const [name, details] of [
+      ['planner', 'Dry run: planner execution skipped; no agent provider was invoked.'],
+      ['coder', 'Dry run: coder execution skipped; no product files were changed.'],
+      ['tester', 'Dry run: tester execution skipped; no verification gates were executed.'],
+      ['reviewer', 'Dry run: reviewer execution skipped; no product files were changed.'],
+    ]) {
+      phases.push({ name, iteration: 1, status: 'passed', details })
+    }
+    return { completed: true, implementationPlan, fileChanges, verification: [], issues, phases, iterations: 1 }
+  }
+
+  const recordPhase = (name, status, details, iteration) => {
+    const phase = { name, status, details }
+    if (iteration) phase.iteration = iteration
+    phases.push(phase)
+    return phase
+  }
+
+  recordPhase('planner', 'running', 'Validating task input and preparing an implementation plan.')
+  const plan = await runAgent('planner', { phase: 'planner', input, implementationPlan })
+  phases[phases.length - 1] = { name: 'planner', status: plan.ok ? 'passed' : 'failed', details: plan.details }
+  if (plan.payload?.implementationPlan?.length) {
+    implementationPlan.splice(0, implementationPlan.length, ...plan.payload.implementationPlan)
+  }
+  if (!plan.ok) issues.push(plan.details)
+
+  let lastVerification = []
+  let completed = false
+  for (let iteration = 1; iteration <= maxIterations && issues.length === 0; iteration += 1) {
+    const before = snapshot()
+    recordPhase('coder', 'running', 'Applying the approved implementation plan.', iteration)
+    const coder = await runAgent('coder', { phase: 'coder', input, implementationPlan, iteration, previousVerification: lastVerification })
+    phases[phases.length - 1] = { name: 'coder', iteration, status: coder.ok ? 'passed' : 'failed', details: coder.details }
+
+    for (const file of changedFiles(before, snapshot())) {
+      fileChanges.push({ file, change: `Changed during coder iteration ${iteration}.` })
+    }
+    if (!coder.ok) {
+      issues.push(coder.details)
+      break
+    }
+
+    recordPhase('tester', 'running', 'Running required verification gates.', iteration)
+    const verification = await runVerification()
+    const externalTest = await runAgent('tester', { phase: 'tester', input, implementationPlan, verification, iteration })
+    if (!externalTest.ok) verification.push({ command: 'external tester', result: 'fail', details: externalTest.details })
+    lastVerification = verification
+    const testerOk = verification.every((check) => check.result === 'pass')
+      && externalTest.ok
+      && externalTest.payload.approved === true
+    phases[phases.length - 1] = {
+      name: 'tester',
+      iteration,
+      status: testerOk ? 'passed' : 'failed',
+      details: testerOk ? 'All required gates passed and tester approved the evidence.'
+        : externalTest.ok ? 'At least one required gate failed or tester rejected the evidence.' : externalTest.details,
+    }
+    writeVerification(iteration, verification)
+    if (!testerOk && iteration === maxIterations) {
+      issues.push('Verification did not pass before maxIterations was reached.')
+      break
+    }
+    if (!testerOk) continue
+
+    recordPhase('reviewer', 'running', 'Checking scope, output contract, and acceptance criteria.', iteration)
+    const outOfScopeChanges = findOutOfScopeChanges(fileChanges.map(({ file }) => file), policy)
+    const reviewer = await runAgent('reviewer', { phase: 'reviewer', input, implementationPlan, verification, fileChanges, iteration })
+    const reviewerApproved = reviewer.ok && reviewer.payload?.approved === true && outOfScopeChanges.length === 0
+    const reviewerDetails = outOfScopeChanges.length
+      ? `Out-of-scope files changed: ${outOfScopeChanges.join(', ')}`
+      : reviewer.details
+    phases[phases.length - 1] = { name: 'reviewer', iteration, status: reviewerApproved ? 'passed' : 'failed', details: reviewerDetails }
+    if (!reviewerApproved) {
+      issues.push(reviewerDetails)
+      break
+    }
+    completed = true
+    break
+  }
+
+  return {
+    completed,
+    implementationPlan,
+    fileChanges,
+    verification: lastVerification,
+    issues,
+    phases,
+    iterations: phases.filter((phase) => phase.name === 'coder').length,
+  }
+}

package/src/package-manager.mjs

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const detectPackageManager = (root) => {
+  if (existsSync(join(root, 'pnpm-lock.yaml'))) return { name: 'pnpm', command: 'pnpm', args: ['run'] }
+  if (existsSync(join(root, 'yarn.lock'))) return { name: 'yarn', command: 'yarn', args: [] }
+  return { name: 'npm', command: 'npm', args: ['run'] }
+}
+
+export const packageScriptCommand = (root, script) => {
+  const manager = detectPackageManager(root)
+  return {
+    ...manager,
+    args: [...manager.args, script],
+    display: `${manager.command} ${[...manager.args, script].join(' ')}`,
+  }
+}

package/src/policy.mjs

@@ -0,0 +1,19 @@
+export const validatePolicy = (policy) => {
+  if (!policy || typeof policy !== 'object') return 'Policy must be an object.'
+  if (!Array.isArray(policy.allowedProductPaths) || policy.allowedProductPaths.length === 0) {
+    return 'Harness policy must define at least one allowedProductPaths entry.'
+  }
+  if (!Number.isInteger(policy.maxIterations) || policy.maxIterations < 1) {
+    return 'Harness policy maxIterations must be a positive integer.'
+  }
+  if (!Array.isArray(policy.protectedPaths)) return 'Harness policy protectedPaths must be an array.'
+  if (!Array.isArray(policy.requiredChecks)) return 'Harness policy requiredChecks must be an array.'
+  return null
+}
+
+export const findOutOfScopeChanges = (files, policy) => files.filter((file) =>
+  !policy.allowedProductPaths.some((allowedPath) => file.startsWith(allowedPath)),
+)
+
+export const isCommandAllowed = (command, policy) =>
+  !policy.allowedAgentCommands?.length || policy.allowedAgentCommands.includes(command)

package/src/provider.mjs

@@ -0,0 +1,32 @@
+import { parseAgentResponse, validateStageResponse } from './agent.mjs'
+import { runCommand } from './command.mjs'
+
+export const createProviderRunner = ({ root, agents, policy, validator, ajv }) => async (name, payload) => {
+  const config = agents[name]
+  if (!config || config.mode === 'internal') {
+    return { ok: true, details: `${name} completed using the built-in stage.`, payload: {} }
+  }
+  if (config.mode !== 'external' || typeof config.provider !== 'string') {
+    return { ok: false, details: `${name} requires a configured provider in .harness/agents.json.`, payload: {} }
+  }
+  const provider = agents.providers?.[config.provider]
+  if (!provider || typeof provider.command !== 'string' || !Array.isArray(provider.args)) {
+    return { ok: false, details: `${name} provider '${config.provider}' is not configured.`, payload: {} }
+  }
+  if (!isAllowed(provider.command, policy)) {
+    return { ok: false, details: `${name} provider command is not in policy.allowedAgentCommands.`, payload: {} }
+  }
+  const result = await runCommand(root, provider.command, provider.args, { ...payload, provider: config.provider })
+  if (result.code !== 0) {
+    return { ok: false, details: result.stderr.trim() || `${name} exited with code ${result.code}.`, payload: {} }
+  }
+  const response = parseAgentResponse(name, result.stdout, validator, ajv)
+  if (!response.ok) return response
+  const stageError = validateStageResponse(name, response.payload)
+  return stageError
+    ? { ok: false, details: stageError, payload: response.payload }
+    : response
+}
+
+const isAllowed = (command, policy) =>
+  !policy.allowedAgentCommands?.length || policy.allowedAgentCommands.includes(command)

package/src/schema.mjs

@@ -0,0 +1,24 @@
+import Ajv2020 from 'ajv/dist/2020.js'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const loadSchemas = (root) => {
+  const read = (name) => JSON.parse(readFileSync(join(root, '.harness', name), 'utf8'))
+  return {
+    input: read('input.schema.json'),
+    output: read('output.schema.json'),
+    agentResponse: read('agent-response.schema.json'),
+  }
+}
+
+export const createValidators = (schemas) => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false })
+  return {
+    ajv,
+    input: ajv.compile(schemas.input),
+    output: ajv.compile(schemas.output),
+    agentResponse: ajv.compile(schemas.agentResponse),
+  }
+}
+
+export const validationDetails = (ajv, validator) => ajv.errorsText(validator.errors)

package/src/snapshots.mjs

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const listFiles = (root, directory = root, result = []) => {
+  if (!existsSync(directory)) return result
+  for (const entry of readdirSync(directory)) {
+    if (directory === root && ['node_modules', 'dist', '.git'].includes(entry)) continue
+    const path = join(directory, entry)
+    if (statSync(path).isDirectory()) listFiles(root, path, result)
+    else result.push(relative(root, path).replaceAll('\\', '/'))
+  }
+  return result
+}
+
+export const snapshotFiles = (root) => new Map(
+  listFiles(root).map((file) => [file, readFileSync(join(root, file), 'utf8')]),
+)
+
+export const changedFiles = (before, after) => [...new Set([...before.keys(), ...after.keys()])]
+  .filter((file) => !before.has(file) || !after.has(file) || before.get(file) !== after.get(file))