Herdr orchestrator skill and Codex harness runtime A local developer released Harness Runtime, a Codex plugin (v0.1.0) that supports Codex's native goal loop by recording real command results, validating declared outcomes, and reusing verification evidence while its inputs remain valid. The plugin registers command hooks for SessionStart, UserPromptSubmit, PreToolUse, Stop, SessionEnd and Interrupt events, each invoking a Node script (harness.mjs) with short timeouts, and discovers workflow guidance through a configured MCP server. | | diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json | | | new file mode 100644 | | | index 0000000..2ed091c | | | --- /dev/null | | | +++ b/.codex-plugin/plugin.json | | | @@ -0,0 +1,17 @@ | | | +{ | | | + "name": "harness-runtime", | | | + "version": "0.1.0+codex.20261011-task-loop-enrollment-v2", | | | + "description": "Support Codex's native goal loop with observed outcomes, reusable verification, execution context, and owned process monitoring.", | | | + "author": { | | | + "name": "Local developer" | | | + }, | | | + "interface": { | | | + "displayName": "Harness Runtime", | | | + "shortDescription": "Keep goals and verify actual outcomes across turns.", | | | + "longDescription": "Record real command results, validate declared outcomes, and reuse evidence while its inputs remain valid. Codex owns continuation; workflow guidance is discovered through the configured gisool MCP server.", | | | + "developerName": "Local developer", | | | + "category": "Productivity", | | | + "capabilities": , | | | + "defaultPrompt": "Help me use Harness Runtime." | | | + } | | | +} | | | diff --git a/hooks/hooks.json b/hooks/hooks.json | | | new file mode 100644 | | | index 0000000..9a6d023 | | | --- /dev/null | | | +++ b/hooks/hooks.json | | | @@ -0,0 +1,73 @@ | | | +{ | | | + "hooks": { | | | + "SessionStart": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 5, | | | + "additionalContextLimit": 600 | | | + } | | | + | | | + } | | | + , | | | + "UserPromptSubmit": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 5, | | | + "additionalContextLimit": 600 | | | + } | | | + | | | + } | | | + , | | | + "PreToolUse": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 5, | | | + "additionalContextLimit": 600 | | | + } | | | + | | | + } | | | + , | | | + "Stop": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 5 | | | + } | | | + | | | + } | | | + , | | | + "SessionEnd": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 3 | | | + } | | | + | | | + } | | | + , | | | + "Interrupt": | | | + { | | | + "hooks": | | | + { | | | + "type": "command", | | | + "command": "node \"${CODEX HOME:-$HOME/.codex}/harness-runtime/current/scripts/harness.mjs\" hook", | | | + "timeout": 3 | | | + } | | | + | | | + } | | | + | | | + } | | | +} | | | diff --git a/package.json b/package.json | | | new file mode 100644 | | | index 0000000..1d78de6 | | | --- /dev/null | | | +++ b/package.json | | | @@ -0,0 +1 @@ | | | +{"name":"harness-runtime","version":"0.1.0","private":true,"type":"module","scripts":{"test":"node --test test/ .test.mjs","verify":"node scripts/check-runtime.mjs","verify:installed":"node scripts/check-installed.mjs"}} | | | diff --git a/scripts/check-installed.mjs b/scripts/check-installed.mjs | | | new file mode 100644 | | | index 0000000..4f322bf | | | --- /dev/null | | | +++ b/scripts/check-installed.mjs | | | @@ -0,0 +1,29 @@ | | | + /usr/bin/env node | | | +import fs from 'node:fs'; | | | +import os from 'node:os'; | | | +import path from 'node:path'; | | | +import crypto from 'node:crypto'; | | | +import {spawnSync} from 'node:child process'; | | | +import {fileURLToPath} from 'node:url'; | | | + | | | +const root = path.resolve path.dirname fileURLToPath import.meta.url , '..' ; | | | +const base = path.join process.env.CODEX HOME \|\| path.join os.homedir , '.codex' , 'harness-runtime' ; | | | +const hash = value = crypto.createHash 'sha256' .update value .digest 'hex' ; | | | +const git = ...args = {const result = spawnSync 'git', '-C', root, ...args , {encoding: 'utf8', timeout: 2000} ; return result.status === 0 ? result.stdout.trim : null;}; | | | +try { | | | + const release = fs.realpathSync path.join base, 'current' ; | | | + const receipt = JSON.parse fs.readFileSync path.join base, 'installation.json' , 'utf8' ; | | | + const files = 'scripts/harness.mjs','scripts/herdr-identity.mjs','scripts/herdr-binding.mjs', 'scripts/verification.mjs', 'scripts/execution.mjs','scripts/task-loop.mjs','scripts/queue-transport.mjs','scripts/continuation-watch-trigger.mjs','hooks/hooks.json', '.codex-plugin/plugin.json' .map file = {file, | | | + equal: hash fs.readFileSync path.join root, file === hash fs.readFileSync path.join release, file } ; | | | + const help = spawnSync process.execPath, path.join release, 'scripts/harness.mjs' , 'verify', 'help' , {encoding: 'utf8', timeout: 3000} ; | | | + const features = spawnSync 'codex', 'features', 'list' , {encoding: 'utf8', timeout: 10000} ; | | | + const goals = features.status === 0 && /^goals\s+\S+\s+true\s $/m.test features.stdout ; | | | + const result = {source: root, source commit: git 'rev-parse', 'HEAD' , source clean: git 'status', '--porcelain' === '', | | | + release, installed commit: receipt.source commit, installation source: receipt.source, | | | + receipt matches release: receipt.release === release, files match: files.every file = file.equal , files, | | | + verifier available: help.status === 0 && JSON.parse help.stdout .schema?.schema version === 2, | | | + native goals enabled: goals, current unchanged: fs.realpathSync path.join base, 'current' === release}; | | | + console.log JSON.stringify result ; | | | + if result.source clean \|\| result.source commit == result.installed commit \|\| result.installation source == root \|\| | | | + result.receipt matches release \|\| result.files match \|\| result.verifier available \|\| goals \|\| result.current unchanged process.exitCode = 1; | | | +} catch error {console.log JSON.stringify {verified: false, error: error.message} ; process.exitCode = 1;} | | | diff --git a/scripts/check-runtime.mjs b/scripts/check-runtime.mjs | | | new file mode 100644 | | | index 0000000..5d5e5d0 | | | --- /dev/null | | | +++ b/scripts/check-runtime.mjs | | | @@ -0,0 +1,20 @@ | | | + /usr/bin/env node | | | +import fs from 'node:fs'; | | | +import path from 'node:path'; | | | +import {fileURLToPath} from 'node:url'; | | | +import {run} from 'node:test'; | | | + | | | +const root = path.resolve path.dirname fileURLToPath import.meta.url , '..' ; | | | +const files = fs.readdirSync path.join root, 'test' .filter name = name.endsWith '.test.mjs' .sort .map name = path.join root, 'test', name ; | | | +let summary = null; | | | +const failures = ; | | | +for await const event of run {files} { | | | + if event.type === 'test:summary' && event.data.file summary = event.data; | | | + if event.type === 'test:fail' failures.push {name: event.data.name, message: event.data.details?.error?.message} ; | | | +} | | | +const result = {success: Boolean summary?.success , executed: summary?.counts?.tests ?? 0, | | | + passed: summary?.counts?.passed ?? 0, failed: summary?.counts?.failed ?? null, | | | + cancelled: summary?.counts?.cancelled ?? null, skipped: summary?.counts?.skipped ?? null, | | | + todo: summary?.counts?.todo ?? null, duration ms: summary?.duration ms ?? null, failures}; | | | +console.log JSON.stringify result ; | | | +if result.success \|\| result.executed \|\| result.failed \|\| result.cancelled \|\| result.skipped \|\| result.todo process.exitCode = 1; | | | diff --git a/scripts/continuation-watch-trigger.mjs b/scripts/continuation-watch-trigger.mjs | | | new file mode 100644 | | | index 0000000..a98b5da | | | --- /dev/null | | | +++ b/scripts/continuation-watch-trigger.mjs | | | @@ -0,0 +1,90 @@ | | | +import fs from 'node:fs'; | | | +import path from 'node:path'; | | | +import crypto from 'node:crypto'; | | | +import {execFileSync} from 'node:child process'; | | | +import {pathToFileURL} from 'node:url'; | | | + | | | +export const enrollmentHash=value= crypto.createHash 'sha256' .update String value .digest 'hex' ; | | | +const id=value= typeof value==='string'&&/^ a-zA-Z0-9 a-zA-Z0-9. :- {0,199}$/.test value ; | | | +const absolute=value= typeof value==='string'&&value.length<=4096&&path.isAbsolute value ; | | | +function mapping config { | | | + const c=config,p=c?.parent; | | | + if c?.schema version ==1\|\| 'armed','cancelled','enrolled' .includes c.state \|\| id c.task id \|\| id c.workspace id \|\| id c.goal tab \|\| p\|\| id p.session id \|\| id p.pane id \|\| absolute p.cwd \|\| 'project root','state root','claim file','registration script','canary result' .every k= absolute c k return null; | | | + const max=c.max emissions??3,retry=c.retry after ms??60000; | | | + if Number.isSafeInteger max \|\|max<1\|\|max 3\|\| Number.isSafeInteger retry \|\|retry<60000\|\|retry 300000 return null; | | | + return {schema version:1,task id:c.task id,workspace id:c.workspace id,goal tab:c.goal tab,project root:c.project root,parent:{session id:p.session id,pane id:p.pane id,cwd:p.cwd},expires at:c.expires at,state root:c.state root,claim file:c.claim file,registration script:c.registration script,canary result:c.canary result,max emissions:max,retry after ms:retry}; | | | +} | | | +export function evaluateEnrollment {config,snapshot,previous=null,now=Date.now ,observed at,guards}={} { | | | + const reject=reason= {event:null,state:previous,reason} ,m=mapping config ; | | | + if m\|\| Number.isFinite now return reject 'invalid mapping' ; | | | + if config.state =='armed' return reject config.state ; | | | + const expiry=Date.parse m.expires at ,observed=Date.parse observed at ; | | | + if Number.isFinite expiry \|\|expiry<=now\|\|expiry-now 3600000 return reject 'expired or unbounded' ; | | | + if Number.isFinite observed \|\|observed now\|\|now-observed 30000 return reject 'snapshot not fresh' ; | | | + if guards\|\|guards.bound ==false\|\|guards.claimed ==false return reject 'bound claimed or guard unavailable' ; | | | + if guards.canary passed ==true\|\|guards.paths present ==true return reject 'activation prerequisite' ; | | | + if Array.isArray snapshot?.tabs \|\| Array.isArray snapshot?.agents return reject 'snapshot invalid' ; | | | + const tabs=snapshot.tabs.filter t= t?.tab id===m.goal tab ,agents=snapshot.agents; | | | + if tabs?.length ==1\|\|tabs 0 .workspace id ==m.workspace id\|\| Array.isArray agents return reject 'goal identity' ; | | | + const parents=agents.filter a= a?.pane id===m.parent.pane id ,sessionMatches=agents.filter a= a?.agent session?.value===m.parent.session id ; | | | + if parents.length ==1\|\|sessionMatches.length ==1 return reject 'parent identity' ; | | | + const a=parents 0 ; | | | + if a.agent =='codex'\|\|a.agent session?.kind =='id'\|\|a.agent session.value ==m.parent.session id\|\|a.workspace id ==m.workspace id\|\|a.tab id ==m.goal tab\|\|a.cwd ==m.parent.cwd\|\|a.foreground cwd&&a.foreground cwd ==m.parent.cwd return reject 'parent identity' ; | | | + if 'idle','done' .includes a.agent status return reject 'parent not ready' ; | | | + const configHash=enrollmentHash JSON.stringify m ; | | | + if previous&& previous.schema version ==1\|\|previous.config hash ==configHash\|\| Number.isSafeInteger previous.emissions \|\|previous.emissions<1\|\|previous.emissions m.max emissions\|\| Number.isFinite previous.next emission at return reject 'receipt invalid or mapping changed' ; | | | + if previous?.emissions =m.max emissions return reject 'emission budget' ; | | | + if previous?.next emission at now return reject 'unchanged backoff' ; | | | + const emissions= previous?.emissions\|\|0 +1,eventId=enrollmentHash 'enrollment:'+configHash ; | | | + const event={type:'harness-enrollment-ready',event id:eventId,emission:emissions,task id:m.task id,workspace id:m.workspace id,goal tab:m.goal tab,project root:m.project root,parent:m.parent,expires at:m.expires at,claim file:m.claim file,registration script:m.registration script,observed at,source:'herdr live'}; | | | + return {event,state:{schema version:1,config hash:configHash,event id:eventId,emissions,last emitted at:new Date now .toISOString ,next emission at:now+m.retry after ms},reason:'ready'}; | | | +} | | | +export function composeWatchResult original,event { | | | + if event return original; | | | + return {...original,fire:true,message:JSON.stringify {type:'herdr-watch-and-enrollment',original message:original.message??null,enrollment:event} }; | | | +} | | | +function readJson file {const stat=fs.statSync file ;if stat.isFile \|\|stat.size 262144 throw Error 'invalid resource' ;return JSON.parse fs.readFileSync file,'utf8' ;} | | | +function exists file {try{fs.lstatSync file ;return true;}catch e {if e.code==='ENOENT' return false;throw Error 'resource unavailable' ;}} | | | +function guardsFor c,now { | | | + const canary=readJson c.canary result ,at=Date.parse canary.verified at ; | | | + return {bound:exists path.join c.state root,'sessions',enrollmentHash c.parent.session id ,'task-membership.json' \|\|exists path.join c.state root,'tasks',enrollmentHash c.task id +'.json' ,claimed:exists c.claim file , | | | + canary passed:canary.status==='pass'&&canary.synthetic===true&&canary.actual continuations===1&&canary.actual turn trigger==='queue'&&canary.business mutations===0&&canary.queue empty===true&&canary.terminal bindings inactive===true&&Number.isFinite at &&at<=now&&now-at<=3600000, | | | + paths present: c.project root,c.parent.cwd,c.state root .every p= fs.statSync p .isDirectory &&fs.statSync c.registration script .isFile }; | | | +} | | | +export async function runWatchTrigger {previous={},config file,original file,state file,timeout ms=10000} { | | | + const deadline=Date.now +Math.max 1,Math.min 10000,Number.isFinite timeout ms ?timeout ms:10000 ; | | | + const run=args= {if Date.now =deadline throw Object.assign Error 'deadline' ,{code:'ETIMEDOUT'} ;return execFileSync 'herdr',args,{encoding:'utf8',timeout:Math.max 1,Math.min 3000,deadline-Date.now ,maxBuffer:2 1024 1024,stdio: 'ignore','pipe','pipe' } ;}; | | | + let original,snapshot,observed at; | | | + try{ | | | + const source=await import pathToFileURL original file .href ;snapshot=JSON.parse run 'api','snapshot' .result.snapshot;observed at=new Date .toISOString ; | | | + original=source.evaluate snapshot,previous,pane= run 'agent','read',pane,'--source','recent-unwrapped','--lines','100' ; | | | + if previous.failure {original.fire=true;original.message=JSON.stringify {recovery:'Herdr connection recovered',update:original.message} ;} | | | + }catch error { | | | + const failure=String error.code\|\|error.status\|\|'read-failed' ; | | | + return {fire:previous.failure ==failure,message:JSON.stringify {type:'monitor-error',reason:'Herdr 상태나 작업 내용을 읽지 못했습니다.',code:failure} ,state:{...previous,failure}}; | | | + } | | | + let lock,owned=false; | | | + try{ | | | + if Date.now =deadline\|\| config file,state file .every absolute return original; | | | + const config=readJson config file ;if mapping config return original; | | | + fs.mkdirSync path.dirname state file ,{recursive:true,mode:0o700} ;lock=state file+'.lock'; | | | + // Fail closed on an existing/abandoned lock; never unlink another owner. | | | + fs.mkdirSync lock,{mode:0o700} ;owned=true; | | | + const previousEmission=exists state file ?readJson state file :null; | | | + const result=evaluateEnrollment {config,snapshot,previous:previousEmission,now:Date.now ,observed at,guards:guardsFor config,Date.now } ; | | | + if result.event\|\|Date.now =deadline return original; | | | + // Detection never claims delivery. Recheck revocation/binding/claim before | | | + // receipt publication; watcher must repeat these checks before its prompt. | | | + const latest=readJson config file ; | | | + if latest.state =='armed'\|\|JSON.stringify mapping latest ==JSON.stringify mapping config \|\|guardsFor latest,Date.now .bound\|\|exists latest.claim file \|\|Date.parse latest.expires at <=Date.now return original; | | | + const temporary=path.join lock,'receipt.json' ;fs.writeFileSync temporary,JSON.stringify result.state +'\n',{mode:0o600} ;fs.renameSync temporary,state file ; | | | + return composeWatchResult original,result.event ; | | | + }catch{return original;}finally{if owned {try{fs.rmdirSync lock ;}catch{}}} | | | +} | | | +async function main { | | | + const args=process.argv.slice 2 ;let previous={};if args 0 && args 0 .startsWith '--' previous=JSON.parse args.shift ; | | | + const values={};while args.length {const flag=args.shift ,value=args.shift ;if '--config','--original','--state' .includes flag \|\| value\|\|values flag throw Error 'invalid arguments' ;values flag =value;} | | | + if '--config','--original','--state' .every k= absolute values k throw Error 'explicit absolute paths required' ; | | | + console.log JSON.stringify await runWatchTrigger {previous,config file:values '--config' ,original file:values '--original' ,state file:values '--state' } ; | | | +} | | | +if process.argv 1 &&fs.existsSync process.argv 1 &&import.meta.url===pathToFileURL fs.realpathSync process.argv 1 .href main .catch = {console.error 'continuation watch arguments invalid' ;process.exitCode=1;} ; | | | diff --git a/scripts/execution.mjs b/scripts/execution.mjs | | | new file mode 100644 | | | index 0000000..43ce0a7 | | | --- /dev/null | | | +++ b/scripts/execution.mjs | | | @@ -0,0 +1,168 @@ | | | +import fs from 'node:fs'; | | | +import path from 'node:path'; | | | +import crypto from 'node:crypto'; | | | +import {spawnSync} from 'node:child process'; | | | + | | | +const hash = value = crypto.createHash 'sha256' .update value .digest 'hex' ; | | | +const object = value = value && typeof value === 'object' && Array.isArray value ; | | | +const read = file = {try {return JSON.parse fs.readFileSync file,'utf8' ;} catch {return null;}}; | | | + | | | +// Deliberately recognize only simple shell commands. Never execute a shell to | | | +// discover its cwd, expand arguments, or treat quoted source text as a command. | | | +export function commandArgs command { | | | + if Array.isArray command return command.every x= typeof x==='string' ?command:null; | | | + if typeof command =='string'\|\| /^\s \w./=- + ?: \t + \w./=- + \s $/.test command return null; | | | + return command.trim .split / \t +/ ; | | | +} | | | +export function gitPreflight command,cwd { | | | + const args=commandArgs command ; | | | + if args?.length\|\|path.basename args 0 =='git' return {status:'not applicable'}; | | | + if cwd\|\| path.isAbsolute cwd return {status:'unverified',reason:'effective cwd unavailable'}; | | | + let effective=cwd,i=1; | | | + while args i ==='-C' { | | | + if args i+1 return {status:'unverified',reason:'git arguments unrecognized'}; | | | + effective=path.resolve effective,args i+1 ;i+=2; | | | + } | | | + const subcommand=args i ; | | | + // These operations really require a repository. Other commands init, clone, | | | + // rev-parse probes, --version, diff --no-index, aliases keep Git's semantics. | | | + if 'status','worktree','branch','log','show','commit','add','reset','checkout','switch','restore','merge','rebase','fetch','pull','push','tag','diff' .includes subcommand \|\| | | | + subcommand==='diff'&&args.includes '--no-index' return {status:'not applicable'}; | | | + const result=spawnSync 'git', '-C',effective,'rev-parse','--git-dir' ,{encoding:'utf8',timeout:1500} ; | | | + return result.status===0?{status:'pass',cwd:effective}:{status:'failed',cwd:effective,reason:'repository precondition unverified'}; | | | +} | | | + | | | +// A deliberately small shell lexer: unknown shell syntax stays reviewable. | | | +function shellStages text { | | | + const stages= ;let word='',started=false,quote=null; | | | + const flush= = {if started {stages.at -1 .push word ;word='';started=false;}}; | | | + for let i=0;i