@awebai/oats 0.30.0 → 0.30.1

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -1,213 +0,0 @@
-#!/usr/bin/env node
-import { fs, join, resolve, readJSON, safePath, oats, fail, unlock, redactUrls } from '../lib/io.mjs';
-import { loadBindings } from '../lib/config.mjs';
-import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, harvestOffRecord, sourceSwitch, retireHarvestOff, consultSource } from '../lib/sources.mjs';
-import { harvestStatus, setupHarvest } from '../lib/harvest-status.mjs';
-import { settings } from '../lib/config.mjs';
-import { CONSULT } from '../lib/consult.mjs';
-import { runSource, complete, retry, readRun, requireQualifiedHelper } from '../lib/worker.mjs';
-import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource, forgetMigration } from '../lib/migration.mjs';
-import { inspect, inspectConsultOnly } from '../lib/inspection.mjs';
-import { loadInvocationKnowledgeBinding } from '../lib/binding-wire.mjs';
-import { loadCapturedOkfInvocation, loadOkfSourceReceiptInput, assertOkfInvocationAction, requireOkfAdmittedAction, assertOkfSourceContext, assertOkfRegisteredSourceReplay } from '../lib/invocation-context.mjs';
-const HELP=`oats okf inspect [--home PATH | --source FILE] [--json]
-oats okf harvest [--home PATH] [--no-launch] [--json]
-oats okf run-source --source FILE [--manual] [--no-launch] [--json]
-oats okf complete --source FILE --run ID --judgment FILE [--json]
-oats okf retry --source FILE [--run ID --rejudge | --rejudge | --launch | --adopt-home PATH] [--json]
-oats okf bases [--fresh] [--json]
-oats okf index [--base ALIAS] [NODE | ALIAS/NODE] [--fresh] [--json]
-oats okf cat --base ALIAS PATH [--from PATH] [--fresh] [--json]
-oats okf ls --base ALIAS [DIR] [--fresh] [--json]
-oats okf links --base ALIAS PATH [--fresh] [--json]
-oats okf search [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive] TEXT [--fresh] [--json]
-Consult commands read the accepted state remotely (host cache, no local copy);
-also accept --home PATH | --source FILE. PATH is /node/x.md from the base root,
-relative to --from's directory, or bare node/x.md from the root.
-oats okf setup --source FILE [--enable | --disable] [--install-host] [--json]
-oats okf setup --harvest on|off [--json]      (writes oats-local.yaml settings.oats.okf.harvest)
-oats okf harvest-status [--soul NAME] [--json]  (the effective harvest switch, why, and the registered sources)
-oats okf init --base ALIAS --nodes FILE [--output PATH | --confirm] [--json]
-oats okf migrate --legacy PATH --base ALIAS --node NODE --output PATH [--json]
-oats okf migrate --deliver FILE | --cutover FILE --soul-dir PATH [--json]
-oats okf migrate --source-home PATH [--json]
-oats okf migrate --forget ID [--json]
-oats okf unlock --lock PATH --token TOKEN [--json]
-Captured workers use oats operation run knowledge:harvest with SOURCE --deployment/--resolution/--home,
---arg native-request=ABS_BACKEND_ONLY_JSON and optional --arg worker-mode=prepare|launch.
-Raw captured harvest/run-source/scheduler/rejudge remain held; completed runs use SOURCE complete/retry.
-Unknown scaffold/native outcomes are retained, never automatically re-scaffolded or redispatched.
-Explicit retry --run ID requires --rejudge; add --launch only for operator-approved launch.
-Closed-PR recovery uses retained evidence and a fresh run; complete its returned ID.
-Settled destinations and old proposals/receipts are preserved; another active run blocks recovery.
-All settings use one absolute bindings-file. Setup host installation is explicit.
-`;
-const args=process.argv.slice(2);
-if(args.includes('--help') || args.includes('-h')) {process.stdout.write(HELP);}
-else {
-  const event=process.env.OATS_EVENT || args[0];
-  const hook=['spawn','retire','soul-scaffold'].includes(event);
-  const consult=Object.hasOwn(CONSULT,event);
-  let exit=0,answer,text,textMode=consult && !args.includes('--json');
-  try {
-    const flags={},positionals=[]; const boolean=new Set(['json','no-launch','manual','rejudge','launch','enable','disable','install-host','confirm','fresh','all','regex','case-sensitive']);
-    for(let i=1;i<args.length;i++) {
-      if(consult && args[i]==='--') {positionals.push(...args.slice(i+1));break;}
-      if(!args[i].startsWith('--')) {if(!consult) fail('E_USAGE',`unexpected argument ${args[i]}`);positionals.push(args[i]);continue;}
-      const k=args[i].slice(2);if(k in flags) fail('E_USAGE',`duplicate --${k}`);
-      if(boolean.has(k)) flags[k]=true;
-      else {if(!args[i+1] || args[i+1].startsWith('--')) fail('E_USAGE',`--${k} needs a value`);flags[k]=args[++i];}
-    }
-    const accepted={
-      spawn:[],retire:['home'], 'soul-scaffold':[],
-      harvest:['home','no-launch','native-request','worker-mode'],inspect:['home','source'],
-      'run-source':['source','manual','no-launch'],complete:['source','run','judgment'],
-      retry:['source','run','rejudge','launch','adopt-home'],read:['home','source','base','path','fresh'],refresh:['home','source'],'harvest-status':['home'],
-      bases:['home','source','fresh'],index:['home','source','base','fresh'],cat:['home','source','base','from','fresh'],ls:['home','source','base','fresh'],
-      links:['home','source','base','fresh'],search:['home','source','base','all','node','regex','case-sensitive','fresh'],
-      setup:['source','enable','disable','install-host','harvest'],init:['base','nodes','output','confirm'],
-      migrate:['source-home','legacy','base','node','output','deliver','cutover','soul-dir'],unlock:['lock','token']
-    };
-    for(const k of Object.keys(flags)) if(!['json','soul',...(accepted[event] || [])].includes(k)) fail('E_USAGE',`unknown flag --${k} for ${event}`);
-    if(flags.source && flags.home) fail('E_USAGE','choose source descriptor OR home');
-    const execution=Object.hasOwn(process.env,'OATS_INVOCATION_CONTEXT_FILE')?loadCapturedOkfInvocation():null;
-    const invocation=execution?{kind:'captured',binding:execution.binding}:loadInvocationKnowledgeBinding(),captured=invocation.kind==='captured';
-    if(execution) assertOkfInvocationAction(execution.context,event,readJSON(new URL('../oats.json',import.meta.url)));
-    // Only an actual admitted, instance-scoped kernel operation can create a
-    // captured worker. Raw commands/null intents and legacy ingress stay closed.
-    const capturedHarvest=captured && execution?.context.action.kind==='operation' && execution.context.action.slot==='knowledge' && execution.context.action.name==='harvest';
-    if(captured && event==='harvest') {
-      if(!capturedHarvest)requireQualifiedHelper({providerBinding:invocation.binding});
-      requireOkfAdmittedAction(execution.context);
-      if(!flags['native-request']||!['prepare','launch'].includes(flags['worker-mode']||'launch'))fail('E_CAPTURED_HELPER','captured harvest needs explicit native-request and supported worker-mode');
-    }
-    const unsupportedCaptured=new Set(['setup','init','migrate','unlock']);
-    if(captured && unsupportedCaptured.has(event)) fail('E_MIGRATION',`captured ${event} is not supported; use an explicit operator administration path`);
-    const target=execution?.context.instance;
-    if(target && flags.home && resolve(flags.home)!==target.home) fail('E_INVOCATION','captured invocation target differs from requested home');
-    const home=target?.home || resolve(flags.home || (execution?process.cwd():process.env.OATS_INSTANCE_HOME || process.env.OATS_HOME || process.cwd()));
-    if(execution && ['spawn','retire'].includes(event)) requireOkfAdmittedAction(execution.context);
-    const sourceReceipt=execution?loadOkfSourceReceiptInput(execution):loadInvocationSourceReceipt(home);
-    if(sourceReceipt.mode==='captured' && !['spawn','retire'].includes(event)) fail('E_SOURCE','captured source receipt is valid only for lifecycle hooks');
-    const src=()=>{
-      try {
-        const source=flags.source?loadSource(resolve(flags.source)):homeSource(home);
-        if(execution) assertOkfSourceContext(source,execution.context,execution.binding);
-        else if(captured) assertOkfRegisteredSourceReplay(source,invocation.binding);
-        else if(source.providerBinding && event!=='inspect') fail('E_INVOCATION','captured source execution requires its selected binding');
-        return source;
-      } catch(error) {if(captured && ['ENOENT','ENOTDIR'].includes(error.code)) fail('E_SOURCE','captured command requires its durable registered source descriptor');throw error;}
-    };
-    // okf 4.0.3: consultation never depends on harvest. A home spawned with
-    // harvest off has no registered source by design; it consults through its
-    // soul's declaration and the deployment's bindings (consultSource).
-    const consultOnly=!flags.source && !captured && !execution && !fs.existsSync(markerPath(home)) && !!harvestOffRecord(home);
-    // Deliberate old registered-source replay is a separate qualified contract,
-    // never a way to create a source or synthesize generic admission. A present
-    // invalid/unadmitted generic invocation cannot enter this compatibility path.
-    if(captured && !execution && Object.hasOwn(accepted,event) && event!=='soul-scaffold') {
-      if(!fs.existsSync(flags.source?resolve(flags.source):markerPath(home))) fail('E_ADMISSION','new captured registration requires generic admitted invocation inputs');
-      src();
-    }
-    if(['spawn','retire'].includes(event)) {
-      // A generic intent authorizes its action, not missing source/role input.
-      // Absence may replay an already qualified source, never create one or
-      // infer a helper skip from an ambient kind/name/knowledge-slot heuristic.
-      if(captured && sourceReceipt.mode!=='captured' && !fs.existsSync(markerPath(home))) fail('E_SOURCE','new captured registration requires SourceReceipt1 input authority');
-      if(execution && fs.existsSync(markerPath(home))) src();
-      if(!captured && fs.existsSync(join(home,'instance.json')) && Object.hasOwn(readJSON(safePath(join(home,'instance.json'))),'executionBinding')) fail('E_INVOCATION','captured home cannot use legacy lifecycle ingress');
-    }
-    // Scope commands have no kernel instance intent. They may finish only
-    // already retained runs under their exact source binding/descriptor, never
-    // allocate a new worker or infer an incarnation for a deleted source.
-    const retainedRun=s=>{
-      const id=event==='complete'?flags.run:loadStatus(s).activeRun;
-      if(!id) {if(event==='complete') fail('E_RUN','complete requires an existing --run');requireQualifiedHelper(s);}
-      readRun(s,id);return s;
-    };
-    let result;
-    if(event==='read') fail('E_REMOVED','okf 4.0.0 removed read: use `oats okf cat --base ALIAS PATH` (same path, text and receipt)');
-    if(consult) {const answer=CONSULT[event](consultOnly?consultSource(home):src(),flags,positionals);result=answer.result;text=answer.text;}
-    else if(event==='refresh') fail('E_REMOVED','okf 3.0.0 has no per-instance views; index/cat always read the accepted state: run `oats okf index`, then `oats okf cat --base ALIAS PATH`');
-    else if(event==='harvest-status') result=harvestStatus({home,flags});
-    else if(event==='soul-scaffold') {
-      // Souls are portable declarations, never an implicit knowledge store.
-      result={meta:{scaffolded:false},brief:'OKF requires explicit external bindings and soul/okf.json before a working instance can spawn. Use init or migrate; no knowledge was created in this soul.'};
-    } else if(event==='spawn') {
-      const s=sourceReceipt.mode==='captured'?registerCaptured(home,sourceReceipt.receipt):register(home);
-      const nodes=(list)=>list.join(', ') || 'none';
-      const brief=decl=>`Your soul knowledge is read remotely at its accepted state; there is no local copy. Start every task with your instance knowledge (STATE.md, log.md, notes/), then \`oats okf index\` (owns: ${nodes(decl.owns)}; reads: ${nodes(decl.reads.filter(r=>!decl.owns.includes(r)))}) and \`oats okf cat --base ALIAS PATH\` for the concepts the task needs; \`oats okf search\` before re-deriving a decision. Load okf-consultation and okf-instance-knowledge. Never edit accepted knowledge.`;
-      if(s.skipped) result={meta:{memory:'none'},brief:'Service agent: follow your own task; no working-memory upkeep.'};
-      else if(s.harvestOff) result={meta:{memory:'okf-v2',harvest:'off',reason:s.switch.reason},brief:`${brief(s.decl)} Harvest is off for this instance: nothing of this session is captured.`,...(s.switch.warnings.length?{warning:`oats-okf: ${s.switch.warnings.join('; ')}`}:{})};
-      else {
-        const schedule=loadStatus(s).schedule.result;
-        result={meta:{memory:'okf-v2',harvest:'on',source:s.file,schedule},brief:`${brief(s.decl)} Harvest is on: your notes and session are captured for the knowledge harvester.`};
-      }
-    } else if(event==='retire') {
-      if(captured) {
-        let s;
-        if(sourceReceipt.mode==='captured') {s=registerCaptured(home,sourceReceipt.receipt);if(s.skipped) {result={meta:{retired:true,reason:'service'}};s=null;}}
-        else {if(!fs.existsSync(markerPath(home))) fail('E_MIGRATION','captured retire requires a durable registered source or explicit helper receipt');s=src();}
-        if(s) {scheduleSource(s);const r=capture(s,{final:true});const schedule=settleRetiredSchedule(s);result={meta:{retired:r.complete===true,source:s.file,capture:r,schedule},brief:'Final input is in durable custody. Delivery remains asynchronous.'};}
-      } else if(service(home)) result={meta:{retired:true}};
-      else if(!fs.existsSync(markerPath(home)) && harvestOffRecord(home)) result={meta:{retired:true,reason:'harvest-off'}};
-      else if(!fs.existsSync(markerPath(home))) {
-        if(['STATE.md','log.md','notes','.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p)))) fail('E_MIGRATION','unregistered/legacy source has memory; explicitly migrate/register before retirement');
-        result={meta:{retired:true,reason:'nothing-to-delete'}};
-      } else {
-        const s=src(),sw=sourceSwitch(s);
-        // okf 4.0.1 #6: harvest switched off since spawn (deployment or soul) → no final capture.
-        if(sw.effective!=='on') result={meta:retireHarvestOff(s,sw),brief:`Harvest is now off (${sw.reason}): no final capture was taken; earlier inputs stay in custody.`};
-        else {scheduleSource(s);const r=capture(s,{final:true});const schedule=settleRetiredSchedule(s);result={meta:{retired:r.complete===true,source:s.file,capture:r,schedule},brief:'Final input is in durable custody. Delivery remains asynchronous.'};}
-      }
-    } else if(event==='harvest') {
-      if(capturedHarvest) {
-        const s=src(); // existing registered descriptor ONLY; never new registration.
-        result=runSource(s,{manual:true,noLaunch:!!flags['no-launch']||flags['worker-mode']==='prepare',capturedInvocation:execution.context,nativeRequest:flags['native-request']});
-      } else {
-        if(flags['native-request']||flags['worker-mode'])fail('E_USAGE','native-request/worker-mode require an admitted captured operation');
-        // Snapshot absence does not turn a persisted captured source into legacy.
-        if(fs.existsSync(markerPath(home))) requireQualifiedHelper(src());
-        const s=register(home);
-        if(s.harvestOff) fail('E_HARVEST_OFF',`harvest is off for this instance: ${s.switch.reason}. Nothing was captured.`);
-        result=s.skipped?{status:'skipped',reason:'service'}:runSource(s,{manual:true,noLaunch:!!flags['no-launch']});
-      }
-    } else if(event==='run-source') {
-      // The deployment can switch harvest off after a source registered: the
-      // job then captures and processes nothing (the soul's opt-out was already
-      // applied at registration). Nothing drains when it is switched back on.
-      const source=src(),sw=sourceSwitch(source);
-      result=sw.effective!=='on'?{status:'harvest-off',source:source.file,reason:`${sw.reason}; nothing was captured`}
-        :runSource(source,{manual:!!flags.manual,noLaunch:!!flags['no-launch']});
-    }
-    else if(event==='complete') {const s=src();if(captured) retainedRun(s);result=complete(s,flags.run,flags.judgment && resolve(flags.judgment));}
-    else if(event==='retry') {const s=src();if(captured && !flags.run && !flags.rejudge && !flags.launch && !flags['adopt-home']) retainedRun(s);result=retry(s,{run:flags.run,rejudge:!!flags.rejudge,launch:!!flags.launch,adoptHome:flags['adopt-home']});}
-    else if(event==='inspect') result=consultOnly?inspectConsultOnly(consultSource(home)):inspect(src());
-    else if(event==='setup' && flags.harvest!==undefined) {
-      if(flags.source || flags.enable || flags.disable || flags['install-host']) fail('E_USAGE','setup --harvest takes no other setup flag');
-      result=setupHarvest(flags.harvest);
-    }
-    else if(event==='setup') {
-      const s=src();if(flags.enable && flags.disable) fail('E_USAGE','choose enable or disable');
-      scheduleSource(s);
-      if(flags.enable || flags.disable) {oats(['schedule',flags.enable?'enable':'disable',`okf-${s.id}`,'--dir',s.context,'--json'],s.context);updateStatus(s,current=>{current.auto=!!flags.enable;});}
-      if(flags['install-host']) oats(['schedule','host','install','--dir',s.context,'--json'],s.context);
-      result={source:s.file,scheduler:oats(['schedule','list','--dir',s.context,'--json'],s.context).scheduler};
-    } else if(event==='init') result=initBase(loadBindings(),flags.base,flags.nodes,flags.output,{confirm:!!flags.confirm});
-    else if(event==='migrate') {
-      if(flags['source-home']) result=migrateSource(loadBindings(),flags['source-home']);
-      else if(flags.forget) result=forgetMigration(loadBindings(),flags.forget);
-      else if(flags.deliver) result=deliverMigration(resolve(flags.deliver));
-      else if(flags.cutover) result=cutoverMigration(resolve(flags.cutover),flags['soul-dir']);
-      else result=migrate(loadBindings(),{legacy:flags.legacy,alias:flags.base,node:flags.node,output:flags.output});
-    } else if(event==='unlock') result=unlock(resolve(flags.lock),flags.token);
-    else fail('E_USAGE',`unknown command ${event}; see --help`);
-    answer=hook?result:{schemaVersion:1,ok:true,result};
-  } catch(e) {const code=e.code || 'E_OKF',message=redactUrls(e.message);exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:message}:{})},warning:`oats-okf ${code}: ${message}`}:{schemaVersion:1,ok:false,error:{code,message}};}
-  // Consult commands print text unless --json; every other answer is JSON.
-  // Let Node drain the pipe; no process.exit after a possibly large answer.
-  if(textMode && exit) process.stderr.write(`oats okf ${event}: ${answer.error.code}: ${answer.error.message}\n`);
-  else if(textMode) process.stdout.write(text+'\n');
-  else process.stdout.write(JSON.stringify(answer)+'\n');
-  process.exitCode=exit;
-}

package/capabilities/oats-okf/injects/okf.md

@@ -1,42 +0,0 @@
-## Knowledge: OKF
-
-You have two kinds of knowledge. Work WITH both: consult them at the start of
-every task, after compaction, and every so often while you work, to decide,
-to situate the task and to stay coherent with what your soul already knows.
-
-- **Soul knowledge**: your soul's accepted OKF bases, external to the soul and
-  read remotely at their accepted state (there is no local copy).
-  **Consultation** reads them with the `oats okf` CLI from your instance home.
-  Load the **okf-consultation** skill at the start of every task.
-- **Instance knowledge**: this instance's own STATE.md, log.md and notes/ in
-  instance home. Load the **okf-instance-knowledge** skill: it teaches what is
-  worth capturing, not only where to put it.
-
-The work mode:
-- **At task start and after compaction:** read STATE.md, recent log.md
-  entries and the relevant notes/, then `oats okf index` and
-  `oats okf cat --base ALIAS PATH` for the concepts the task needs. Follow
-  links; do not bulk-load.
-- **Before compaction and before a task boundary:** update STATE.md, log.md
-  and notes/ first, so your future self can continue.
-- **Every so often while working, and always before a design decision or
-  before re-deriving something:** `oats okf search` / `cat` the relevant
-  concepts and re-read your own notes. Consult prior decisions before
-  re-deriving them.
-- Cite what you relied on as `alias/node/concept.md@<short-oid>`. A Git PR is
-  not accepted knowledge until it is merged. Report missing configuration or
-  blocked reads; do not create a substitute.
-
-**Capture with judgment**, as it happens: decisions and why, rejected
-alternatives, costly discoveries, limitations and the workaround that worked,
-conclusions, blockers, human direction and corrections, and surprises that
-contradict soul knowledge (flag those as candidate supersessions). Not code
-descriptions, command logs, retries, secrets, verbatim third-party messages,
-or what the tracker and docs already hold. One concept per note in notes/;
-STATE.md is the current picture (rewritten); log.md is dated events
-(append-only). The knowledge harvester, not you, decides what is promoted.
-
-**Never write accepted knowledge or soul knowledge.** This is an instruction
-boundary, not a filesystem sandbox. Skills remain curated soul artifacts.
-Instance knowledge lives in instance home, not ./work; code and repository
-documentation remain the truth about code.