@getopencrawl/cli 0.1.0 → 0.1.1

package/src/research-agent.mjs

@@ -3,7 +3,7 @@ import {readResearchAnswerContract} from './research-answer-contract.mjs';
 import {readResearchAnswerView} from './research-answer-view.mjs';
 import fs from 'node:fs/promises';
 import {createHash} from 'node:crypto';
-import {allowedOptions,decimal,identifier,withInterrupt} from './jobs.mjs';
+import {allowedOptions,decimal,identifier,settle,transient,withInterrupt} from './jobs.mjs';
 import {displayLine,displayText} from './display.mjs';
 
 const ROOT='/api/research/agents',ACTIVE=new Set(['queued','running']);
@@ -27,7 +27,7 @@ function confirmedReadFailure(error,request){
  const message={
   401:'Saved research could not be read. Check the selected CLI account, server and workspace and its existing credential.',
   403:'This account cannot read the requested research. Check the selected account and workspace and ask its administrator to confirm access.',
-  404:request.command==='receipt'?'The original admission receipt is unavailable to this account. Check the selected workspace and exact operation. A missing receipt does not authorize a new admission.':'The saved research is unavailable to this account. Check the selected workspace and exact agent, run or source identifiers. Do not substitute a current webpage for retained evidence.',
+  404:request.command==='receipt'?'The original admission receipt is unavailable to this account. Check the selected workspace and exact operation. A missing receipt does not authorize a new admission.':'The saved research is unavailable to this account. Check the selected workspace and exact agent, run or source identifiers. Do not substitute a current webpage for retained evidence. Watches, jobs and research built by the OpenCrawl agent belong to their project: use that project\'s key (project.api_key from the build), not the organization key.',
   409:'The saved research could not be read in its current state. Read the same agent, schedule or feedback and reconcile its current revision before any write.'
  }[error.status];
  return message?{code:`http_${error.status}`,message}:null;
@@ -127,7 +127,7 @@ export function agentRequest(rest,options){
  return {...base,id,route,method:'PATCH',body:{expected_revision:revision,status:command==='pause'?'paused':'active'}};
 }
 async function readDescriptor(file){const handle=await fs.open(file,'r');try{const size=(await handle.stat()).size;if(!integer(size,1,65536))throw new Error('Research brief JSON must be between 1 byte and 64 KiB.');const bytes=Buffer.alloc(size+1),read=await handle.read(bytes,0,size+1,0);if(read.bytesRead!==size)throw new Error('Research brief changed while reading.');let value;try{value=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes.subarray(0,size)))}catch{throw new Error('Invalid research brief JSON. Supply valid UTF-8 JSON without extra fields.');}return validateAgentDescriptor(value)}finally{await handle.close()}}
-export async function waitAgentRun(client,initial,{timeout,signal,now=()=>performance.now(),sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms))}={}){let run=validateAgentRun(initial);const started=now();let deadline=started+(timeout??([2,3].includes(readResearchCompletion(run).completion?.version??0)?540:300))*1000;while(ACTIVE.has(run.status)){if(signal?.aborted)return {run,wait:{outcome:'interrupted'}};if(now()>=deadline)return {run,wait:{outcome:'timeout'}};try{run=validateAgentRun(await client.request(`${ROOT}/${encodeURIComponent(run.agent_id)}/runs/${encodeURIComponent(run.id)}`,{signal,timeout:Math.max(1,Math.min(30000,Math.ceil(deadline-now()))),maxResponseBytes:262144}),run.agent_id,run.id)}catch(error){const outcome=signal?.aborted?'interrupted':now()>=deadline?'timeout':'unavailable',failure=outcome==='unavailable'?confirmedReadFailure(error,{command:'agent-run'}):null;return {run,wait:{outcome,...(failure?{error:failure}:{})}}}if(timeout===undefined&&[2,3].includes(readResearchCompletion(run).completion?.version??0))deadline=started+540000;if(ACTIVE.has(run.status)){const next=Math.min(deadline,now()+2000);while(!signal?.aborted&&now()<next)await sleep(Math.min(100,next-now()));}}return {run,wait:{outcome:run.status}};}
+export async function waitAgentRun(client,initial,{timeout,signal,now=()=>performance.now(),sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms))}={}){let run=validateAgentRun(initial),failures=0;const started=now();let deadline=started+(timeout??([2,3].includes(readResearchCompletion(run).completion?.version??0)?540:300))*1000;while(ACTIVE.has(run.status)){if(signal?.aborted)return {run,wait:{outcome:'interrupted'}};if(now()>=deadline)return {run,wait:{outcome:'timeout'}};try{run=validateAgentRun(await client.request(`${ROOT}/${encodeURIComponent(run.agent_id)}/runs/${encodeURIComponent(run.id)}`,{signal,timeout:Math.max(1,Math.min(30000,Math.ceil(deadline-now()))),maxResponseBytes:262144}),run.agent_id,run.id);failures=0}catch(error){if(!signal?.aborted&&now()<deadline&&transient(error)){await settle(++failures,{signal,now,sleep,deadline});continue;}const outcome=signal?.aborted?'interrupted':now()>=deadline?'timeout':'unavailable',failure=outcome==='unavailable'?confirmedReadFailure(error,{command:'agent-run'}):null;return {run,wait:{outcome,...(failure?{error:failure}:{})}}}if(timeout===undefined&&[2,3].includes(readResearchCompletion(run).completion?.version??0))deadline=started+540000;if(ACTIVE.has(run.status)){const next=Math.min(deadline,now()+2000);while(!signal?.aborted&&now()<next)await sleep(Math.min(100,next-now()));}}return {run,wait:{outcome:run.status}};}
 function renderRun(run,stdout){stdout(`Run: ${displayLine(run.id)}\nAgent: ${displayLine(run.agent_id)}\nStatus: ${displayLine(run.status)}\n`);const answer=readResearchAnswerView(run);if(answer.state==='valid'&&answer.sections.some(s=>s.assertions.length)){stdout('\nConcise answer\n');for(const section of answer.sections){stdout('\n'+displayText(section.component.text)+'\n');for(const assertion of section.assertions)stdout(displayText(assertion.text)+'\n');if(section.notice)stdout(displayText(section.notice)+'\n');const evidenceIds=section.assertions.length?[...new Set(section.assertions.flatMap(a=>a.fact_refs.flatMap(r=>run.findings.find(f=>f.id===r.finding_id)?.citations.map(c=>c.id)??[])))]:section.component.evidence_ids;if(evidenceIds.length)stdout('Evidence: '+evidenceIds.map(displayLine).join(', ')+'\n');}stdout('\nExact findings and qualifications\n');}for(const finding of run.findings){stdout(`\n${displayLine(finding.id)}\nObserved statement: ${displayText(finding.claim)}\n`);if(finding.relevance!=='Selected for this research brief.')stdout(`Relevance (inference): ${displayText(finding.relevance)}\n`);for(const qualifier of finding.qualifiers)stdout('Qualification: '+displayText(qualifier)+'\n');for(const cite of finding.citations)stdout(`[${displayLine(cite.id)}] ${displayLine(cite.title)}\n${displayLine(cite.url)}\nObserved: ${displayLine(cite.observed_at)}; source positions ${cite.start}–${cite.end}\n${displayText(cite.quote)}\n`);}for(const gap of [...run.gaps,...readResearchAnswerContract(run).notices.map(notice=>notice.text),...readResearchCompletion(run).notices.map(notice=>notice.text)])stdout('Gap: '+displayText(gap)+'\n');const presentation=readResearchPresentation(run);if(presentation&&!['reviewed','skipped_no_eligible'].includes(presentation.status))stdout('Summary: A concise presentation was not completed for every part. The saved findings and gaps remain available.\n');if(run.error)stdout('Run error: '+displayLine(run.error.message)+'\n');}
 export async function agentCommand(rest,options,client,{stdout=value=>process.stdout.write(value),stderr=value=>process.stderr.write(value)}={}){
  const request=agentRequest(rest,options);if(request.file)request.body=await readDescriptor(request.file);
@@ -148,7 +148,7 @@ export async function agentCommand(rest,options,client,{stdout=value=>process.st
   else if(request.command==='repeats')validateAgentRepeats(value,request.id,request.runId);
   else if(request.command==='agent-run')validateAgentRun(value,request.id,request.runId);
   else {validateResearchAgent(value,request.id);if(['pause','resume'].includes(request.command)&&(value.status!==request.body.status||![request.body.expected_revision,request.body.expected_revision+1].includes(value.revision)))invalid();}
- }catch(error){const status=Number.isInteger(error?.status)?error.status:undefined,message=confirmedReadFailure(error,request)?.message??(request.command==='feedback'?'Feedback was not confirmed. Read the same finding feedback and reconcile its revision before another write.':request.command==='source'?'Saved source context could not be read. Do not substitute a current webpage for this saved observation.':request.command==='schedule'?'Schedule request was not confirmed. Read the same schedule and reconcile its setting and revision before another write.':'Research request was not confirmed. Read the same agent/run or recover the original admission key; never start a duplicate blindly.');const result={error:{code:status?`http_${status}`:'request_unconfirmed',message,...(request.key?{request_key:request.key}:{})}};if(options.json)stdout(JSON.stringify(result,null,2)+'\n');else stderr(message+(request.key?'\nOriginal request key: '+request.key:'')+'\n');return 1;}
+ }catch(error){const status=Number.isInteger(error?.status)?error.status:undefined,message=confirmedReadFailure(error,request)?.message??(request.command==='feedback'?'Feedback was not confirmed. Read the same finding feedback and reconcile its revision before another write.':request.command==='source'?'Saved source context could not be read. Do not substitute a current webpage for this saved observation.':request.command==='schedule'?'Schedule request was not confirmed. Read the same schedule and reconcile its setting and revision before another write.'+(status===409&&error.detail?' Server: '+error.detail:''):'Research request was not confirmed. Read the same agent/run or recover the original admission key; never start a duplicate blindly.');const result={error:{code:status?`http_${status}`:'request_unconfirmed',message,...(request.key?{request_key:request.key}:{})}};if(options.json)stdout(JSON.stringify(result,null,2)+'\n');else stderr(message+(request.key?'\nOriginal request key: '+request.key:'')+'\n');return 1;}
  if(request.command==='feedback'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else stdout(`Feedback: ${displayLine(value.feedback.state)}\nRevision: ${value.feedback.revision}\nRating: ${displayLine(value.feedback.rating??'none')}\n${value.feedback.note===null?'':displayText(value.feedback.note)+'\n'}Customer feedback is not independent factual proof.\n`);return 0;}
  if(request.command==='source'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else stdout(`Saved source context: ${displayLine(value.source.id)}\n${displayLine(value.source.title)}\n${displayLine(value.source.url)}\nObserved: ${displayLine(value.source.observed_at)}\nThis is the admitted evidence window, which may be part of a page.\n\n${displayText(value.source.text)}\n`);return 0;}
  if(request.command==='runs'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else{for(const run of value.items)stdout(`${displayLine(run.id)}\t${displayLine(run.status)}\t${displayLine(run.created_at)}\n`);stderr(`Next cursor: ${displayLine(value.next_cursor)}\nMore admitted runs: ${value.has_more?'yes':'no'}\nRetain pending run IDs and read each exact run until terminal.\n`);}return 0;}

package/src/research-agent.test.mjs

@@ -0,0 +1,231 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {researchCommand} from './research.mjs';
+import {agentRequest,validateAgentDescriptor,validateAgentRun,waitAgentRun} from './research-agent.mjs';
+
+const stamp='2026-10-24T08:00:00.000Z',id='ragent_'+'a'.repeat(32),runId='job_'+'b'.repeat(32),key='agent-request-key-0001';
+const input={customer:{name:'Atlas',website:'https://atlas.example/',context:''},goal:'Find workflow changes.',collection_ids:[],schedule_minutes:0};
+const run=(patch={})=>({id:runId,agent_id:id,agent_revision:1,status:'queued',phase:'queued',created_at:stamp,started_at:null,finished_at:null,outcome:null,findings:[],gaps:[],usage:{},error:null,...patch});
+const agent=(patch={})=>({id,...input,revision:1,status:'active',created_at:stamp,updated_at:stamp,latest_run:run(),...patch});
+const receipt={agent:agent(),run:run(),replayed:false};
+const citation={id:'W1',url:'https://source.example/release',title:'Release',quote:'é🌲 claim',start:3,end:11,body_sha256:'a'.repeat(64),observed_at:stamp,published_at:'October 2026',source_kind:'web_search',collection_id:null,document_id:null,version_id:null};
+const completed=()=>run({status:'completed',phase:'finished',started_at:stamp,finished_at:stamp,outcome:'findings',findings:[{id:'finding_one',claim:'The vendor announces a workflow.',relevance:'This may be relevant to Atlas.',qualifiers:['Enterprise only.'],citations:[citation]}]});
+async function execute(rest,options,value){let stdout='',stderr='';const calls=[];const code=await researchCommand(rest,options,{request:async(route,args)=>{calls.push({route,args});if(value instanceof Error)throw value;return typeof value==='function'?value(calls.length):value}},{stdout:x=>stdout+=x,stderr:x=>stderr+=x});return {code,stdout,stderr,calls};}
+
+test('execution status exit code is independent of findings and preserves legacy or new coverage diagnostics',async()=>{
+ for(const [status,usage,code] of [['partial',{},2],['completed',{evidence_limits:{version:1,reasons:[]}},0],['partial',{evidence_limits:{version:1,reasons:['finding_omitted']}},2]]){
+  const value={...completed(),status,outcome:'no_supported_findings',findings:[],gaps:['This bounded run is not an exhaustive survey.'],usage};
+  const json=await execute(['agent-run',id,runId],{json:true},value),display=await execute(['agent-run',id,runId],{},value);
+  assert.equal(json.code,code);assert.deepEqual(JSON.parse(json.stdout),value);assert.equal(json.calls.length,1);
+  assert.equal(display.code,code);assert.ok(display.stdout.includes(value.gaps[0]));assert.equal(display.calls.length,1);
+ }
+});
+
+test('five findings preserve text order, own sources and full JSON; six and oversized packets emit no findings',async()=>{
+ const value=completed();value.findings=Array.from({length:5},(_,index)=>({...structuredClone(value.findings[0]),id:`finding_${index}`,claim:`Workflow ${index+1} has a documented export.`,qualifiers:[`Export ${index+1} requires Enterprise approval.`],citations:[{...citation,id:`W${index+1}`,url:`https://source.example/workflow/${index+1}`,quote:`Export ${index+1} is documented.`,start:0,end:23}]}));
+ const json=await execute(['agent-run',id,runId],{json:true},value),display=await execute(['agent-run',id,runId],{},value);
+ assert.equal(json.code,0);assert.deepEqual(JSON.parse(json.stdout),value);assert.equal(json.calls.length,1);assert.equal(display.code,0);assert.equal(display.calls.length,1);
+ let previous=-1;for(const finding of value.findings){const position=display.stdout.indexOf(finding.claim);assert.ok(position>previous);previous=position;for(const text of [...finding.qualifiers,finding.citations[0].url,finding.citations[0].quote])assert.ok(display.stdout.includes(text))}
+ const six={...value,findings:[...value.findings,{...value.findings[0],id:'finding_six'}]},oversized=structuredClone(value);
+ for(const finding of oversized.findings)finding.citations=Array.from({length:3},()=>({...citation,quote:'🌲'.repeat(1200),start:0,end:1200}));
+ assert.ok(Buffer.byteLength(JSON.stringify({findings:oversized.findings,gaps:oversized.gaps}))>32768);
+ for(const invalid of [six,oversized]){const rejected=await execute(['agent-run',id,runId],{json:true},invalid);assert.equal(rejected.code,1);assert.equal(rejected.calls.length,1);assert.ok(!rejected.stdout.includes(value.findings[0].claim))}
+});
+
+test('saved run JSON and display retain all five full qualifiers without truncation',async()=>{
+ const value=completed();value.findings[0].qualifiers=Array.from({length:5},(_,i)=>`${i+1}:`+'x'.repeat(298));
+ const json=await execute(['agent-run',id,runId],{json:true},value);
+ assert.equal(json.code,0);assert.deepEqual(JSON.parse(json.stdout),value);assert.equal(json.calls.length,1);
+ const display=await execute(['agent-run',id,runId],{},value);
+ assert.equal(display.code,0);for(const qualifier of value.findings[0].qualifiers)assert(display.stdout.includes(qualifier));
+ for(const qualifiers of [[...value.findings[0].qualifiers,'Sixth condition.'],[...value.findings[0].qualifiers.slice(0,4),'x'.repeat(301)]]){
+  const invalid=structuredClone(value);invalid.findings[0].qualifiers=qualifiers;
+  assert.throws(()=>validateAgentRun(invalid,id,runId));
+ }
+});
+
+test('failure diagnostic reads preserve JSON and failed exit without a retry',async()=>{
+ for(const usage of [{},{failure:{version:1,phase:'review',check:'response_contract'}}]){
+  const value=run({status:'failed',phase:'finished',started_at:stamp,finished_at:stamp,usage,error:{code:'invalid_output',message:'The research output could not be validated.'}});
+  const result=await execute(['agent-run',id,runId],{json:true},value);
+  assert.equal(result.code,1);assert.deepEqual(JSON.parse(result.stdout),value);assert.equal(result.calls.length,1);
+  assert.throws(()=>validateAgentRun({...value,usage:{padding:'x'.repeat(16385)}},id,runId));
+ }
+});
+
+test('history reads one page and prints persistent checkpoint including empty tail',async()=>{
+ const page={items:[run()],next_cursor:'next',has_more:true};
+ const result=await execute(['agent','runs',id],{limit:'1',cursor:'prior',json:true},page);
+ assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),page);assert.equal(result.calls.length,1);
+ assert.equal(result.calls[0].route,`/api/research/agents/${id}/runs?limit=1&cursor=prior`);assert.equal(result.calls[0].args.method,undefined);assert.equal(result.calls[0].args.maxResponseBytes,1048576);
+ const empty=await execute(['agent','runs',id],{cursor:'next'},{items:[],next_cursor:'next',has_more:false});
+ assert.equal(empty.code,0);assert.match(empty.stderr,/Next cursor: next/);assert.match(empty.stderr,/More admitted runs: no/);
+ for(const options of [{limit:'101'},{cursor:'é'},{cursor:'bad\n'},{wait:true},{'request-key':key}])assert.throws(()=>agentRequest(['agent','runs',id],options));
+});
+test('history refuses malformed page without emitting partial source text or guessed cursor',async()=>{
+ const good={items:[completed()],next_cursor:'next',has_more:false};
+ for(const value of [{...good,extra:true},{...good,next_cursor:null},{...good,has_more:1},{...good,next_cursor:'prior'},
+  {...good,items:[],has_more:true},{...good,items:[]},{...good,items:[run(),run()]},{...good,items:[run({agent_id:'wrong'})]},
+  {...good,items:[run({status:['queued']})]}]){
+  const result=await execute(['agent','runs',id],{cursor:'prior',json:true},value);assert.equal(result.code,1);assert(!result.stdout.includes('Enterprise only.'));assert(!result.stdout.includes('next_cursor'));
+ }
+ const error=new Error('PRIVATE_SOURCE');error.status=404;const denied=await execute(['agent','runs',id],{cursor:'prior',json:true},error);
+ assert.equal(denied.code,1);assert.equal(denied.calls.length,1);assert(!denied.stdout.includes('PRIVATE_SOURCE'));assert(!denied.stdout.includes('next_cursor'));
+});
+test('history enforces whole-envelope byte bound before rendering',async()=>{
+ const items=Array.from({length:70},(_,i)=>run({id:'job_'+String(i).padStart(32,'0'),usage:{text:'🌲'.repeat(4000)}}));
+ const result=await execute(['agent','runs',id],{limit:'100',json:true},{items,next_cursor:'next',has_more:false});assert.equal(result.code,1);assert(!result.stdout.includes('🌲'));
+});
+
+test('agent request parser binds exact routes, offsets and operation keys',()=>{
+ assert.deepEqual(agentRequest(['agent-run',id,runId],{json:true}).route,`/api/research/agents/${id}/runs/${runId}`);
+ const rerun=agentRequest(['agent','run',id],{revision:'1','request-key':key});assert.equal(rerun.method,'POST');assert.deepEqual(rerun.body,{expected_revision:1});
+ assert.equal(agentRequest(['agent','receipt'],{operation:'run:'+id,'request-key':key}).method,undefined);
+ for(const args of [[['agent','run',id],{'request-key':key}],[['agent-run',id,runId],{timeout:'2'}],[['agent','create'],{file:'brief.json','request-key':key,bypass:true}],[['agent','show',id,'extra'],{}]])assert.throws(()=>agentRequest(...args));
+});
+test('brief validation normalizes website and rejects oversized or broadened descriptors',()=>{
+ assert.equal(validateAgentDescriptor({...input,customer:{name:'Atlas',website:'HTTPS://ATLAS.EXAMPLE:443/#section'}}).customer.website,input.customer.website);
+ for(const patch of [{schedule_minutes:60},{schedule_minutes:true},{collection_ids:['x','x']},{goal:'\ud800'},{extra:'PRIVATE'},{customer:{name:'Atlas',website:'https://user:secret@x.example/'}}])assert.throws(()=>validateAgentDescriptor({...input,...patch}));
+});
+test('create sends exactly one reviewed descriptor, retains recovery key and no source API',async()=>{
+ const dir=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-agent-')),file=path.join(dir,'brief.json');
+ try{await fs.writeFile(file,JSON.stringify(input));const value=await execute(['agent','create'],{file,'request-key':key,json:true},receipt);assert.equal(value.code,0);assert.equal(value.calls.length,1);assert.equal(value.calls[0].route,'/api/research/agents');assert.deepEqual(value.calls[0].args.body,input);assert.equal(value.calls[0].args.idempotencyKey,key);assert.equal(JSON.parse(value.stdout).run.status,'queued');}
+ finally{await fs.rm(dir,{recursive:true,force:true})}
+});
+test('malformed brief never sends and never echoes private bytes',async()=>{
+ const dir=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-agent-')),file=path.join(dir,'brief.json');
+ try{await fs.writeFile(file,'{"PRIVATE_SYNTHETIC_SECRET');await assert.rejects(execute(['agent','create'],{file,'request-key':key},receipt),error=>!error.message.includes('PRIVATE_SYNTHETIC_SECRET'));}
+ finally{await fs.rm(dir,{recursive:true,force:true})}
+});
+test('unknown run admission never retries and prints only fixed error plus original key',async()=>{
+ const value=await execute(['agent','run',id],{revision:'1','request-key':key,json:true},new Error('PRIVATE_SYNTHETIC_SECRET'));
+ assert.equal(value.code,1);assert.equal(value.calls.length,1);assert.equal(JSON.parse(value.stdout).error.request_key,key);assert.ok(!value.stdout.includes('PRIVATE_SYNTHETIC_SECRET'));
+});
+test('plain findings preserve exact quote, qualifier, inference and source range',async()=>{
+ const value=await execute(['agent-run',id,runId],{},completed());assert.equal(value.code,0);assert.equal(value.calls.length,1);
+ for(const expected of ['Observed statement:','Relevance (inference):','Qualification: Enterprise only.','é🌲 claim','source positions 3–11','https://source.example/release'])assert.ok(value.stdout.includes(expected));
+});
+test('neutral relevance is hidden only in text while saved JSON and historical values remain intact',async()=>{
+ const value=completed();value.findings[0].relevance='Selected for this research brief.';
+ value.usage={model_stages:{version:2,synthesis_calls:1,review_calls:1,draft_findings:1,review_decisions:[{ordinal:1,selected_quotes_support_all_claims_and_qualifiers:true,source_context_preserves_restrictions_and_date:true,addresses_requested_goal:true}]}};
+ const display=await execute(['agent-run',id,runId],{},value);assert.equal(display.code,0);assert.equal(display.calls.length,1);
+ assert(!display.stdout.includes('Relevance (inference):'));assert(!display.stdout.includes(value.findings[0].relevance));
+ for(const expected of [value.findings[0].claim,'Qualification: Enterprise only.',citation.quote,citation.url,'source positions 3–11'])assert(display.stdout.includes(expected));
+ const json=await execute(['agent-run',id,runId],{json:true},value);assert.equal(json.code,0);assert.equal(json.calls.length,1);assert.deepEqual(JSON.parse(json.stdout),value);
+ for(const relevance of ['This may be relevant to Atlas.','Selected for this research brief. ']){
+  value.findings[0].relevance=relevance;const historical=await execute(['agent-run',id,runId],{},value);assert.equal(historical.code,0);assert(historical.stdout.includes('Relevance (inference): '+relevance));
+ }
+});
+test('invalid scope/Unicode/citation kinds/internal fields never emit source text',async()=>{
+ const cases=[completed(),completed(),completed(),completed(),completed()];cases[0].id='wrong';cases[1]._source_fences=[];cases[2].findings[0].citations=[{...citation,end:12}];cases[3].findings[0].citations=[{...citation,source_kind:'indexed'}];cases[4].findings[0].claim='\ud800';
+ for(const value of cases){const result=await execute(['agent-run',id,runId],{json:true},value);assert.equal(result.code,1);assert.ok(!result.stdout.includes('é🌲 claim'));}
+});
+test('same source may support two exact quotes and hash remains supplied evidence metadata',()=>{
+ const value=completed();value.findings[0].citations.push({...citation,quote:'claim',start:6,end:11,body_sha256:'f'.repeat(64)});assert.deepEqual(validateAgentRun(value),value);
+});
+test('read terminal failed, unknown, partial and needs-input remain distinct exit states',async()=>{
+ for(const [status,code] of [['partial',2],['failed',1],['unknown',1],['cancelled',1],['needs_input',1]]){const value=run({status,phase:'finished',finished_at:stamp,outcome:status==='needs_input'?'needs_input':null});const result=await execute(['agent-run',id,runId],{json:true},value);assert.equal(result.code,code);assert.equal(JSON.parse(result.stdout).status,status);}
+});
+test('wait uses only exact GET and interrupted wait never cancels or creates work',async()=>{
+ let clock=0;const calls=[];const result=await waitAgentRun({request:async(route,args)=>{calls.push({route,args});return calls.length===1?run({status:'running',phase:'researching'}):completed()}},run(),{now:()=>clock,sleep:async ms=>{clock+=ms}});
+ assert.equal(result.wait.outcome,'completed');assert.ok(calls.every(c=>c.route===`/api/research/agents/${id}/runs/${runId}`&&!c.args.method));
+ const controller=new AbortController();controller.abort();const stopped=await waitAgentRun({request:async()=>assert.fail()},run(),{signal:controller.signal});assert.equal(stopped.wait.outcome,'interrupted');
+});
+test('list reads one page only and historical receipt stays queued',async()=>{
+ const page=await execute(['agent','list'],{limit:'1',json:true},{items:[agent()],next_cursor:'next'});assert.equal(page.calls.length,1);assert.equal(JSON.parse(page.stdout).next_cursor,'next');
+ const recovered=await execute(['agent','receipt'],{operation:'create','request-key':key,json:true},{...receipt,replayed:true});assert.equal(recovered.calls[0].args.method,undefined);assert.equal(JSON.parse(recovered.stdout).run.status,'queued');
+});
+test('invalid admitted response preserves recovery key and impossible dates never render',async()=>{
+ const result=await execute(['agent','run',id],{revision:'1','request-key':key,json:true},{agent:'PRIVATE_SYNTHETIC_SECRET'});
+ assert.equal(result.calls.length,1);assert.equal(result.code,1);assert.equal(JSON.parse(result.stdout).error.request_key,key);assert.ok(!result.stdout.includes('PRIVATE_SYNTHETIC_SECRET'));
+ assert.throws(()=>validateAgentRun(completedWithDate()));
+ function completedWithDate(){return {...completed(),created_at:'2026-02-30T08:00:00Z'}}
+});
+test('status writes reject a changed requested status or unrelated revision',async()=>{
+ for(const patch of [{revision:8,status:'paused'},{revision:2,status:'active'}]){const result=await execute(['agent','pause',id],{revision:'1',json:true},agent(patch));assert.equal(result.calls.length,1);assert.equal(result.code,1);}
+});
+
+test('actual CLI performs one create and exact keyed GET recovery through the real transport',async()=>{
+ const folder=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-agent-cli-')),calls=[];
+ const server=http.createServer(async(req,res)=>{let body='';for await(const part of req)body+=part;calls.push({path:req.url,method:req.method,key:req.headers['idempotency-key'],authorization:req.headers.authorization,body:body?JSON.parse(body):null});res.setHeader('Content-Type','application/json');res.end(JSON.stringify(req.url.includes('/runs?')?{items:[completed()],next_cursor:'history-next',has_more:false}:req.url.endsWith('/schedule')?(req.method==='PATCH'?daily():schedule()):req.url.endsWith('/repeats')?repeats():req.url.includes('/runs/')?completed():{...receipt,replayed:req.method==='GET'}));});
+ await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));
+ const script=fileURLToPath(new URL('../bin/opencrawl.mjs',import.meta.url)),url='http://127.0.0.1:'+server.address().port;
+ const env={PATH:process.env.PATH,HOME:folder,OPENCRAWL_CONFIG_DIR:folder,OPENCRAWL_URL:url,OPENCRAWL_API_KEY:'synthetic-only-key'};
+ const invoke=args=>new Promise((resolve,reject)=>{const child=spawn(process.execPath,[script,...args],{cwd:folder,env,stdio:['ignore','pipe','pipe']});let stdout='',stderr='';const timer=setTimeout(()=>child.kill('SIGKILL'),10000);child.stdout.on('data',x=>stdout+=x);child.stderr.on('data',x=>stderr+=x);child.on('error',reject);child.on('close',code=>{clearTimeout(timer);resolve({code,stdout,stderr})});});
+ try{
+  const file=path.join(folder,'brief.json');await fs.writeFile(file,JSON.stringify(input));
+  const created=await invoke(['research','agent','create','--file',file,'--request-key',key,'--json']);assert.equal(created.code,0,created.stdout+created.stderr);assert.equal(JSON.parse(created.stdout).run.id,runId);
+  const recovered=await invoke(['research','agent','receipt','--operation','create','--request-key',key,'--json']);assert.equal(recovered.code,0,recovered.stdout+recovered.stderr);assert.equal(JSON.parse(recovered.stdout).replayed,true);
+  const saved=await invoke(['research','agent-run',id,runId,'--json']);assert.equal(saved.code,0,saved.stderr);assert.equal(JSON.parse(saved.stdout).status,'completed');
+  const scheduleRead=await invoke(['research','agent','schedule',id,'--json']);assert.equal(scheduleRead.code,0,scheduleRead.stdout+scheduleRead.stderr);assert.deepEqual(JSON.parse(scheduleRead.stdout),schedule());
+  const scheduled=await invoke(['research','agent','schedule',id,'daily','--revision','0','--json']);assert.equal(scheduled.code,0,scheduled.stdout+scheduled.stderr);assert.deepEqual(JSON.parse(scheduled.stdout),daily());
+  const repeated=await invoke(['research','agent','repeats',id,runId,'--json']);assert.equal(repeated.code,0,repeated.stdout+repeated.stderr);assert.deepEqual(JSON.parse(repeated.stdout),repeats());
+  const history=await invoke(['research','agent','runs',id,'--limit','1','--cursor','history-prior','--json']);assert.equal(history.code,0,history.stdout+history.stderr);assert.deepEqual(JSON.parse(history.stdout),{items:[completed()],next_cursor:'history-next',has_more:false});
+  assert.deepEqual(calls.map(c=>[c.method,c.path]),[['POST','/api/research/agents'],['GET','/api/research/agents/receipts/by-key?operation=create'],['GET',`/api/research/agents/${id}/runs/${runId}`],['GET',`/api/research/agents/${id}/schedule`],['PATCH',`/api/research/agents/${id}/schedule`],['GET',`/api/research/agents/${id}/runs/${runId}/repeats`],['GET',`/api/research/agents/${id}/runs?limit=1&cursor=history-prior`]]);
+  assert.deepEqual(calls[4].body,{expected_revision:0,enabled:true});assert.equal(calls[4].key,undefined);
+  assert.deepEqual(calls[0].body,input);assert.ok(calls.every(c=>c.authorization==='Bearer synthetic-only-key'));assert.equal(calls[0].key,key);assert.equal(calls[1].key,key);assert.equal(calls[2].key,undefined);
+  const invalid=await invoke(['research','agent','run',id,'--revision','1','--request-key',key,'--request-key','duplicate']);assert.equal(invalid.code,1);assert.equal(calls.length,7);
+ }finally{server.closeAllConnections();await new Promise(resolve=>server.close(resolve));await fs.rm(folder,{recursive:true,force:true});}
+});
+const page=patch=>({requested_url:'https://source.example/old-release',final_url:citation.url,body_sha256:'f'.repeat(64),start:100,end:116,total_chars:500,extractor:'public-static-v3',...patch});
+test('page evidence JSON preserves exact window/quote metadata without another fetch',async()=>{
+ const value=completed();value.findings[0].citations=[{...citation,source_kind:'web_page',page:page()}];
+ const result=await execute(['agent-run',id,runId],{json:true},value);assert.equal(result.code,0);assert.equal(result.calls.length,1);assert.deepEqual(JSON.parse(result.stdout),value);
+ const c=JSON.parse(result.stdout).findings[0].citations[0];assert.equal(c.page.start+c.start,103);assert.notEqual(c.body_sha256,c.page.body_sha256);
+});
+test('invalid page metadata or wrong source kind never renders the quote',async()=>{
+ const bad=[null,{},page({extra:true}),page({requested_url:'https://u:p@source.example/'}),page({final_url:'https://other.example/'}),page({body_sha256:'F'.repeat(64)}),page({start:-1}),page({start:true}),page({start:1.5}),page({end:100}),page({end:110}),page({end:501}),page({total_chars:131073}),page({total_chars:true}),page({start:0,end:16001,total_chars:16001}),page({extractor:'unknown'})];
+ for(const metadata of bad){const value=completed();value.findings[0].citations=[{...citation,source_kind:'web_page',page:metadata}];const result=await execute(['agent-run',id,runId],{json:true},value);assert.equal(result.code,1);assert(!result.stdout.includes(citation.quote));}
+ for(const extra of [{source_kind:'web_page'},{source_kind:'web_page',page:page(),version_id:'rver_foreign'},{source_kind:'web_search',page:null},{source_kind:'indexed',collection_id:'rcol_one',document_id:'doc_one',version_id:'rver_one',page:page()}]){const value=completed();value.findings[0].citations=[{...citation,...extra}];assert.throws(()=>validateAgentRun(value));}
+});
+test('legacy source kinds stay readable without page metadata',()=>{
+ for(const c of [citation,{...citation,source_kind:'indexed',collection_id:'rcol_one',document_id:'doc_one',version_id:'rver_one'}]){const value=completed();value.findings[0].citations=[c];assert.deepEqual(validateAgentRun(value),value);}
+});
+
+const schedule=(patch={})=>({agent_id:id,revision:0,enabled:false,schedule_minutes:0,next_scheduled_at:null,blocked_reason:null,blocked_run_id:null,deferred_reason:null,...patch});
+const daily=(patch={})=>schedule({revision:1,enabled:true,schedule_minutes:1440,next_scheduled_at:stamp,...patch});
+const repeats=(patch={})=>({agent_id:id,run_id:runId,status:'available',items:[{finding_id:'finding_current',classification:'first_seen',first_seen_run_id:runId,first_seen_finding_id:'finding_current'}],...patch});
+test('schedule command is explicit, revision-bound and separate from agent pause or run',()=>{
+ assert.deepEqual(agentRequest(['agent','schedule',id],{}),{command:'schedule',id,route:`/api/research/agents/${id}/schedule`});
+ for(const [action,enabled] of [['daily',true],['pause',false],['resume',true]]){const request=agentRequest(['agent','schedule',id,action],{revision:'0',json:true});assert.equal(request.method,'PATCH');assert.deepEqual(request.body,{expected_revision:0,enabled});}
+ for(const [args,options] of [[['agent','schedule',id,'daily'],{}],[['agent','schedule',id,'show'],{revision:'0'}],[['agent','schedule',id,'resume'],{revision:'-1'}],[['agent','schedule',id,'daily'],{revision:'1','request-key':key}],[['agent','schedule',id,'hourly'],{}],[['agent','repeats',id,runId,'extra'],{}]])assert.throws(()=>agentRequest(args,options));
+});
+test('daily and blocked schedules render honestly; mixed agent lists and historical reads work',async()=>{
+ const updated=await execute(['agent','schedule',id,'daily'],{revision:'0',json:true},daily());assert.equal(updated.code,0);assert.deepEqual(updated.calls[0].args.body,{expected_revision:0,enabled:true});assert.equal(updated.calls.length,1);
+ const blocked=await execute(['agent','schedule',id],{},daily({next_scheduled_at:null,blocked_reason:'unknown',blocked_run_id:runId}));assert.equal(blocked.code,0);assert.match(blocked.stdout,/Daily research: enabled/);assert.match(blocked.stdout,/Blocked: unknown/);
+ const deferred=await execute(['agent','schedule',id],{},daily({deferred_reason:'daily_budget'}));assert.match(deferred.stdout,/Deferred: daily_budget/);
+ const mixed=await execute(['agent','list'],{json:true},{items:[agent(),agent({id:'ragent_daily',schedule_minutes:1440,latest_run:null})],next_cursor:null});assert.equal(mixed.code,0);
+ assert.equal((await execute(['agent','receipt'],{operation:'create','request-key':key,json:true},{...receipt,replayed:true})).code,0);
+ assert.throws(()=>validateAgentDescriptor({...input,schedule_minutes:1440}));
+});
+test('schedule failures never retry, substitute a revision or expose invalid response',async()=>{
+ for(const value of [new Error('PRIVATE_SYNTHETIC_SECRET'),daily({agent_id:'other'}),daily({revision:9}),daily({schedule_minutes:0}),daily({next_scheduled_at:null}),daily({blocked_reason:'unexpected'}),daily({extra:'PRIVATE_SYNTHETIC_SECRET'}),daily({deferred_reason:'invented'}),schedule({deferred_reason:'daily_budget'})]){const result=await execute(['agent','schedule',id,'daily'],{revision:'0',json:true},value);assert.equal(result.code,1);assert.equal(result.calls.length,1);assert(!result.stdout.includes('PRIVATE_SYNTHETIC_SECRET'));}
+});
+test('repeat command reads once, distinguishes not assessed and never removes saved findings',async()=>{
+ const value=repeats();const result=await execute(['agent','repeats',id,runId],{json:true},value);assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),value);assert.equal(result.calls.length,1);assert.equal(result.calls[0].route,`/api/research/agents/${id}/runs/${runId}/repeats`);assert.equal(result.calls[0].args.method,undefined);
+ const unassessed=await execute(['agent','repeats',id,runId],{},repeats({status:'not_assessed',items:[]}));assert.match(unassessed.stdout,/not_assessed/);assert.match(unassessed.stdout,/not a judgment of business novelty/);
+ const saved=await execute(['agent-run',id,runId],{json:true},completed());assert.deepEqual(JSON.parse(saved.stdout),completed());
+});
+test('repeat response rejects foreign, duplicate and contradictory first-seen references',async()=>{
+ for(const value of [repeats({status:['available']}),repeats({items:[{...repeats().items[0],classification:['exact_repeat'],first_seen_run_id:'foreign'}]}),repeats({run_id:'foreign'}),repeats({status:'not_assessed'}),repeats({items:[...repeats().items,...repeats().items]}),repeats({items:[{...repeats().items[0],classification:'exact_repeat'}]}),repeats({items:[{...repeats().items[0],classification:'exact_repeat',first_seen_finding_id:'finding_other'}]}),repeats({items:[{...repeats().items[0],first_seen_run_id:'foreign'}]}),repeats({extra:true})]){const result=await execute(['agent','repeats',id,runId],{json:true},value);assert.equal(result.code,1);assert.equal(result.calls.length,1);}
+});
+
+test('source command reads an exact saved window without starting research',async()=>{
+ const {createHash}=await import('node:crypto');const text='Before. é🌲 claim. Requires approval.\r\n';
+ const value={agent_id:id,run_id:runId,source:{id:'W1',url:'https://source.example/release',title:'Release',text,body_sha256:createHash('sha256').update(text).digest('hex'),observed_at:stamp,published_at:null,source_kind:'indexed',collection_id:'rcoll_one',document_id:'doc_one',version_id:'rv_one'}};
+ const result=await execute(['agent','source',id,runId,'W1'],{json:true},value);
+ assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),value);assert.equal(result.calls.length,1);assert.equal(result.calls[0].route,`/api/research/agents/${id}/runs/${runId}/sources/W1`);assert.equal(result.calls[0].args.body,undefined);
+ const display=await execute(['agent','source',id,runId,'W1'],{},value);assert.equal(display.code,0);assert.ok(display.stdout.includes('Requires approval.'));assert.ok(display.stdout.includes('admitted evidence window'));
+ for(const mutate of [v=>v.run_id='other',v=>v.source.id='other',v=>v.source.text+='changed',v=>v.source.body_sha256='0'.repeat(64),v=>v.source.version_id=null,v=>v.source.source_kind='web_search']){
+  const bad=structuredClone(value);mutate(bad);const denied=await execute(['agent','source',id,runId,'W1'],{json:true},bad);assert.equal(denied.code,1);assert.ok(!denied.stdout.includes('Requires approval.'));assert.equal(denied.calls.length,1);
+ }
+});
+test('source command rejects ambiguous or extra arguments before transport',()=>{
+ for(const [rest,options] of [[['agent','source',id,runId],{}],[['agent','source',id,runId,'W1','extra'],{}],[['agent','source',id,runId,'W1'],{wait:true}]])assert.throws(()=>agentRequest(rest,options));
+});

package/src/research-answer-contract.test.mjs

@@ -0,0 +1,14 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {agentCommand} from './research-agent.mjs';
+import {makeRun,saturated,hostile,unknown} from '../../sdk/tests/fixtures/answer-contract-cases.mjs';
+const execute=async(run,json=false)=>{let stdout='',stderr='',calls=0;const code=await agentCommand(['agent-run',run.agent_id,run.id],{json},{request:async()=>{calls++;return run}},{stdout:t=>stdout+=t,stderr:t=>stderr+=t});return {stdout,stderr,calls,code}};
+test('canonical BC03 gap appears once; five saturated notes plus one typed notice retain exact JSON/status',async()=>{
+ for(const r of [makeRun(),saturated()]){const before=JSON.stringify(r),human=await execute(r),json=await execute(r,true);assert.equal(human.code,0);assert.equal(human.calls,1);assert.equal(json.calls,1);assert.deepEqual(JSON.parse(json.stdout),r);assert.equal(JSON.stringify(r),before);assert.equal(human.stdout.split('does not establish an answer or its contradiction').length-1,1);for(const gap of r.gaps)assert(human.stdout.includes(gap));for(const f of r.findings){assert(human.stdout.includes(f.claim));for(const q of f.qualifiers)assert(human.stdout.includes(q))}}
+});
+test('malformed assessment remains an optional warning with preserved literal output and no retry',async()=>{
+ const r=makeRun();r.usage.answer_contract={version:99};r.status='partial';const out=await execute(r);assert.equal(out.code,2);assert.equal(out.calls,1);assert.match(out.stdout,/assessment could not be validated/);assert(out.stdout.includes(r.findings[0].claim));
+});
+test('terminal and bidi controls in assessment are escaped only in human output',async()=>{
+ const r=hostile(),out=await execute(r),json=await execute(r,true);assert.equal(out.code,0);assert(!out.stdout.includes('\u001b'));assert(!out.stdout.includes('\u202e'));assert.match(out.stdout,/\\u001b/);assert.match(out.stdout,/\\u202e/);assert.deepEqual(JSON.parse(json.stdout),r);assert(JSON.parse(json.stdout).usage.answer_contract.components.at(-1).text.includes(unknown(r).text));
+});

package/src/research-answer-view.test.mjs

@@ -0,0 +1,27 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {agentCommand} from './research-agent.mjs';
+import {makeRun,omittedRun,extraSupportedRun} from '../../sdk/tests/fixtures/answer-view-cases.mjs';
+const execute=async(run,json=false)=>{let stdout='',stderr='',calls=0;const code=await agentCommand(['agent-run',run.agent_id,run.id],{json},{request:async()=>{calls++;return run}},{stdout:t=>stdout+=t,stderr:t=>stderr+=t});return {stdout,stderr,calls,code}};
+test('concise prose precedes unchanged exact facts, conditions, citations and every saved gap',async()=>{
+ const r=makeRun();r.status='partial';r.gaps=['Saved gap one.','Saved gap two.'];const before=JSON.stringify(r),human=await execute(r),json=await execute(r,true);
+ assert.equal(human.code,2);assert.equal(human.calls,1);assert(human.stdout.indexOf('Concise answer')<human.stdout.indexOf('Observed statement:'));
+ assert(human.stdout.includes(r.usage.answer_view.sections[0].assertions[0].text));assert(human.stdout.includes('Evidence: P1'));assert(human.stdout.includes('Review the exact evidence'));
+ for(const f of r.findings){assert(human.stdout.includes(f.claim));for(const q of f.qualifiers)assert(human.stdout.includes(q));for(const c of f.citations)assert(human.stdout.includes(c.quote))}for(const g of r.gaps)assert(human.stdout.includes(g));
+ assert.equal(json.calls,1);assert.equal(json.code,2);assert.equal(json.stdout,JSON.stringify(r,null,2)+'\n');assert.equal(JSON.stringify(r),before);
+});
+test('absent and invalid concise metadata leave legacy human output exactly equal',async()=>{
+ const absent=makeRun();delete absent.usage.answer_view;const invalid=structuredClone(absent);invalid.usage.answer_view={version:99};
+ assert.deepEqual(await execute(invalid),await execute(absent));assert.equal((await execute(invalid,true)).stdout,JSON.stringify(invalid,null,2)+'\n');
+});
+test('concise evidence labels include the sources of additional retained supporting fields',async()=>{
+ const r=extraSupportedRun(),out=await execute(r);assert.equal(out.calls,1);assert(out.stdout.includes('Evidence: P1, P2'));
+ assert.equal((await execute(r,true)).stdout,JSON.stringify(r,null,2)+'\n');
+});
+test('source-scoped unknown stays separate and optional prose does not become a complete badge',async()=>{
+ const r=omittedRun('source_scoped_unknown_assessment','source_scoped_unknown'),out=await execute(r);
+ assert(out.stdout.includes('Not established in the saved sources for this part.'));assert(!out.stdout.includes('All questions answered'));assert.equal(out.calls,1);
+});
+test('unsupported terminal-control prose falls back, while raw JSON remains exact',async()=>{
+ const r=makeRun();r.usage.answer_view.sections[0].assertions[0].text+='\u001b';const out=await execute(r),raw=await execute(r,true);assert(!out.stdout.includes('Concise answer'));assert(!out.stdout.includes('\u001b'));assert.equal(raw.stdout,JSON.stringify(r,null,2)+'\n');
+});

package/src/research-completion.test.mjs

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {readResearchCompletion} from './research-completion.mjs';
+import {agentCommand,agentRequest,validateAgentDescriptor} from './research-agent.mjs';
+
+const fixture=JSON.parse(await fs.readFile(new URL('./fixtures/research-completion-v1.json',import.meta.url),'utf8'));
+const actual=JSON.parse(await fs.readFile(new URL('./fixtures/research-completion-hosted.json',import.meta.url),'utf8'));
+const empty={completion:null,notices:[]},metadata=()=>structuredClone(fixture.completion);
+const read=value=>readResearchCompletion({usage:{completion:value}});
+const key='completion-original-key-0001',id=actual.runs.admitted.agent_id;
+const brief={customer:{name:'Northlight',website:'https://northlight.example/',context:''},goal:'Find documented workflow changes.',collection_ids:[],schedule_minutes:0};
+const queued=actual.runs.admitted;
+const receipt={agent:{id,revision:1,status:'active',...brief,created_at:queued.created_at,updated_at:queued.created_at,latest_run:queued},run:queued,replayed:false};
+async function execute(rest,options,result){
+ let stdout='',stderr='';const calls=[];
+ const code=await agentCommand(rest,options,{request:async(route,args)=>{calls.push({route,args});if(result instanceof Error)throw result;return result;}},{stdout:x=>stdout+=x,stderr:x=>stderr+=x});
+ return {code,stdout,stderr,calls};
+}
+
+test('fixed notices preserve order and detach the optional view from saved metadata',()=>{
+ const input=metadata(),before=structuredClone(input),view=read(input);
+ assert.deepEqual(view.completion,before);
+ assert.deepEqual(view.notices,Object.entries(fixture.notice_text).map(([code,text])=>({code,text})));
+ view.completion.notices.pop();view.completion.limits.pages=1;
+ assert.deepEqual(input,before);
+});
+
+test('absent and queued metadata are quiet and cannot imply completion',()=>{
+ for(const run of [{},{usage:{}},{usage:null}])assert.deepEqual(readResearchCompletion(run),empty);
+ const admitted=actual.runs.admitted.usage.completion;
+ assert.deepEqual(read(admitted),{completion:admitted,notices:[]});
+ for(const patch of [{validated_passes:1},{notices:['bounded_sources']},{timing_ms:metadata().timing_ms},{completed_usage_lower_bound:metadata().completed_usage_lower_bound}])assert.deepEqual(read({...admitted,...patch}),empty);
+});
+
+test('malformed, raw or private optional fields never become human notices',()=>{
+ const mutations=[v=>{v.version=2},v=>{v.policy='other'},v=>{v.policy_sha256='a'.repeat(64)},v=>{v.whole_request_completeness='complete'},v=>{v.reason='all_answered'},v=>{v.limits.pages=10},v=>{v.limits.extra=1},v=>{delete v.limits.page_bytes},v=>{v.notices=['PRIVATE_RAW\u001b[31m']},v=>{v.notices=['bounded_sources','bounded_sources']},v=>{v.notices=['toString']},v=>{v.notices=['__proto__']},v=>{v.raw='PRIVATE_RAW'},v=>{delete v.validated_passes},v=>{v.timing_ms=null},v=>{v.completed_usage_lower_bound=[]}];
+ for(const mutate of mutations){const value=metadata();mutate(value);assert.deepEqual(read(value),empty);}
+});
+
+test('integer limits and finite timing phases reject impossible optional measurements',()=>{
+ for(const invalid of [-1,NaN,Infinity,true,'1',0.5])for(const field of ['validated_passes','timing_ms.total','timing_ms.phases.0.elapsed_ms','completed_usage_lower_bound.model_calls','completed_usage_lower_bound.web_searches','completed_usage_lower_bound.input_tokens','completed_usage_lower_bound.output_tokens']){
+  const value=metadata(),parts=field.split('.');let target=value;for(const part of parts.slice(0,-1))target=target[part];target[parts.at(-1)]=invalid;assert.deepEqual(read(value),empty,field);
+ }
+ const mutations=[v=>{v.validated_passes=3},v=>{v.timing_ms.total=360001},v=>{v.timing_ms.phases[0].elapsed_ms=210001},v=>{v.timing_ms.phases.push(v.timing_ms.phases[0])},v=>{v.timing_ms.phases[0].phase='raw'},v=>{v.timing_ms.phases[0].body='private'},v=>{v.completed_usage_lower_bound.model_calls=6},v=>{v.completed_usage_lower_bound.web_searches=6},v=>{v.completed_usage_lower_bound.input_tokens=1000000001}];
+ for(const mutate of mutations){const value=metadata();mutate(value);assert.deepEqual(read(value),empty);}
+});
+
+test('actual API projected admitted repaired unknown and unassessed runs preserve JSON and status on one read',async()=>{
+ assert.deepEqual(Object.keys(actual.runs),['admitted','repaired','unknown','unassessed']);
+ for(const [name,run] of Object.entries(actual.runs)){
+  const before=JSON.stringify(run),options=['agent-run',run.agent_id,run.id];
+  const json=await execute(options,{json:true},run),human=await execute(options,{},run);
+  assert.deepEqual(JSON.parse(json.stdout),run);assert.equal(json.code,human.code);assert.equal(json.calls.length,1);assert.equal(human.calls.length,1);
+  assert.equal(json.calls[0].args.method,undefined);assert.equal(JSON.stringify(run),before);
+  assert.deepEqual(readResearchCompletion(run).completion,run.usage.completion);
+  for(const code of run.usage.completion.notices)assert.ok(human.stdout.includes(fixture.notice_text[code]),name);
+  if(name==='unknown'){assert.equal(json.code,1);assert.equal(run.findings.length,0);assert.equal(readResearchCompletion(run).completion.validated_passes,1);assert.equal(readResearchCompletion(run).notices.length,0);}
+ }
+});
+
+test('all five saved gaps survive, followed by fixed optional notices without changing ordinary findings',async()=>{
+ const run=structuredClone(actual.runs.repaired);run.gaps=Array.from({length:5},(_,i)=>`Saved gap ${i+1}.`);run.usage.completion=metadata();
+ const result=await execute(['agent-run',run.agent_id,run.id],{},run);assert.equal(result.calls.length,1);
+ let previous=-1;for(const text of [...run.gaps,...Object.values(fixture.notice_text)]){const next=result.stdout.indexOf('Gap: '+text);assert.ok(next>previous,text);previous=next;}
+ for(const finding of run.findings){assert.ok(result.stdout.includes(finding.claim));for(const citation of finding.citations)assert.ok(result.stdout.includes(citation.quote));}
+});
+
+test('invalid optional metadata is ignored in human output and preserved verbatim in JSON without extra requests',async()=>{
+ const run=structuredClone(actual.runs.repaired);run.usage.completion={...metadata(),notices:['PRIVATE_RAW']};
+ const human=await execute(['agent-run',run.agent_id,run.id],{},run),json=await execute(['agent-run',run.agent_id,run.id],{json:true},run);
+ assert.equal(human.code,json.code);assert.equal(human.calls.length,1);assert.equal(json.calls.length,1);assert.ok(!human.stdout.includes('PRIVATE_RAW'));
+ assert.deepEqual(JSON.parse(json.stdout),run);for(const finding of run.findings)assert.ok(human.stdout.includes(finding.claim));
+});
+
+test('ordinary descriptor and manual-run body remain byte-identical when policy is absent',()=>{
+ assert.equal(JSON.stringify(validateAgentDescriptor(brief)),JSON.stringify(brief));
+ const request=agentRequest(['agent','run',id],{revision:'1','request-key':key});assert.equal(JSON.stringify(request.body),'\u007b"expected_revision":1}');assert.equal(request.key,key);
+});
+
+test('v1 remains explicit at create JSON and manual-run option',()=>{
+ assert.deepEqual(validateAgentDescriptor({...brief,research_policy:'completion_v1'}),{...brief,research_policy:'completion_v1'});
+ const request=agentRequest(['agent','run',id],{revision:'1','request-key':key,'research-policy':'completion_v1'});assert.deepEqual(request.body,{expected_revision:1,research_policy:'completion_v1'});assert.equal(request.key,key);
+ for(const value of [undefined,null,true,1,'ordinary','completion_v4',{},['completion_v1']]){
+  assert.throws(()=>validateAgentDescriptor({...brief,research_policy:value}),/research_policy/);
+  assert.throws(()=>agentRequest(['agent','run',id],{revision:'1','request-key':key,'research-policy':value}),/research-policy/);
+ }
+ for(const rest of [['agent','show',id],['agent-run',id,queued.id],['agent','schedule',id,'daily'],['agent','create']])assert.throws(()=>agentRequest(rest,{'research-policy':'completion_v1'}),/Unsupported/);
+});
+
+test('create forwards exactly one explicit policy with original key; unavailable policy never falls back',async()=>{
+ const directory=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-completion-')),file=path.join(directory,'brief.json');
+ try{
+  const body={...brief,research_policy:'completion_v1'};await fs.writeFile(file,JSON.stringify(body));
+  const result=await execute(['agent','create'],{file,'request-key':key,json:true},receipt);
+  assert.equal(result.code,0);assert.equal(result.calls.length,1);assert.deepEqual(result.calls[0].args.body,body);assert.equal(result.calls[0].args.idempotencyKey,key);
+  const error=new Error('PRIVATE_SERVER_REASON');error.status=409;
+  const denied=await execute(['agent','create'],{file,'request-key':key,json:true},error);
+  assert.equal(denied.code,1);assert.equal(denied.calls.length,1);assert.equal(JSON.parse(denied.stdout).error.request_key,key);assert.ok(!denied.stdout.includes('PRIVATE_SERVER_REASON'));
+ }finally{await fs.rm(directory,{recursive:true,force:true});}
+});
+
+test('manual admission unknown keeps original policy/key and uses only GET for explicit receipt recovery',async()=>{
+ const result=await execute(['agent','run',id],{revision:'1','request-key':key,'research-policy':'completion_v1',json:true},new Error('PRIVATE_LOST_ACK'));
+ assert.equal(result.code,1);assert.equal(result.calls.length,1);assert.deepEqual(result.calls[0].args.body,{expected_revision:1,research_policy:'completion_v1'});assert.equal(JSON.parse(result.stdout).error.request_key,key);assert.ok(!result.stdout.includes('PRIVATE_LOST_ACK'));
+ const recovered=await execute(['agent','receipt'],{operation:'run:'+id,'request-key':key,json:true},{...receipt,replayed:true});
+ assert.equal(recovered.code,0);assert.equal(recovered.calls.length,1);assert.equal(recovered.calls[0].args.method,undefined);assert.equal(recovered.calls[0].args.idempotencyKey,key);assert.equal(recovered.calls[0].args.body,undefined);
+});

package/src/research-event.test.mjs

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {researchCommand,researchRequest} from './research.mjs';
+import {loggedInConfig} from './client.mjs';
+const stamp='2026-10-24T05:00:00Z',url='https://example.com/product';
+const side=(patch={})=>({version_id:'rver_after',version_sha256:'a'.repeat(64),body_sha256:'b'.repeat(64),title:'Public product',url,final_url:url,extraction_version:'static-v3',version_observed_at:stamp,text:'é🌲 value',start_char:0,end_char:8,full_length:20,next_start_char:8,omitted_before:false,omitted_after:true,window_origin:'page_start',changed_start_char:null,changed_end_char:null,...patch});
+const detail=(patch={})=>({id:'rev_one',collection_id:'rcol_one',url,kind:'baseline',observed_at:stamp,previous_observed_at:null,gap:false,comparison:'single_observation',budget:16000,text_bytes:12,before:null,after:side(),...patch});
+async function execute(value=detail(),options={},rest=['event','rcol_one','rev_one']){let stdout='',stderr='';const calls=[];const code=await researchCommand(rest,options,{request:async(route,params)=>{calls.push({route,params});if(value instanceof Error)throw value;return value}},{stdout:x=>stdout+=x,stderr:x=>stderr+=x});return {code,stdout,stderr,calls};}
+test('event command requires exactly two safe IDs and strict bounded numeric options',()=>{
+ assert.equal(researchRequest(['event','rcol_one','rev_one'],{}).route,'/api/research/collections/rcol_one/events/rev_one?budget=16000');
+ const request=researchRequest(['event','rcol_one','rev_one'],{budget:'256','before-start':'0','after-start':'25'});assert.equal(request.beforeStart,0);assert.equal(request.afterStart,25);assert.match(request.route,/before_start=0&after_start=25$/);
+ for(const rest of [['event'],['event','rcol_one'],['event','rcol_one','rev_one','extra'],['event','rcol_one','../bad']])assert.throws(()=>researchRequest(rest,{}));
+ for(const options of [{budget:'0'},{budget:'32001'},{budget:'1e3'},{budget:true},{'after-start':'-1'},{'after-start':'01'},{'before-start':'2000001'},{wait:true},{cursor:'x'},{'request-key':'key'},{refresh:true}])assert.throws(()=>researchRequest(['event','rcol_one','rev_one'],options));
+});
+test('event JSON is exact, plain observations label omissions and never fetch another page',async()=>{
+ const json=await execute(detail(),{json:true});assert.deepEqual(JSON.parse(json.stdout),detail());assert.equal(json.calls.length,1);assert.equal(json.calls[0].params.method,undefined);assert.equal(json.calls[0].params.body,undefined);
+ const human=await execute();assert.match(human.stdout,/Event: rev_one/);assert.match(human.stdout,/Codepoints: \[0, 8\) of 20/);assert.match(human.stdout,/é🌲 value/);assert.match(human.stderr,/--after-start 8/);assert.match(human.stderr,/not authored modifications/);assert.equal(human.calls.length,1);
+});
+test('bad event evidence emits no source text, including JSON mode',async()=>{
+ for(const value of [detail({id:'foreign'}),detail({collection_id:'foreign'}),detail({budget:256}),detail({text_bytes:11}),detail({comparison:'equal_body'}),detail({after:side({end_char:9})}),detail({after:side({body_sha256:'bad'})}),detail({after:side({next_start_char:9})}),detail({after:side({omitted_after:false})}),detail({after:side({text:'\ud800',end_char:1})}),detail({text_bytes:20000,after:side({text:'🌲'.repeat(5000),end_char:5000,full_length:5000,next_start_char:null,omitted_after:false})})]){
+  let output='';await assert.rejects(researchCommand(['event','rcol_one','rev_one'],{json:true},{request:async()=>value},{stdout:s=>output+=s,stderr:()=>{}}),/invalid or out-of-scope/);assert.equal(output,'');
+ }
+});
+test('explicit offsets include zero/end and absent sides fail closed',async()=>{
+ const end=detail({text_bytes:0,after:side({text:'',start_char:20,end_char:20,next_start_char:null,omitted_before:true,omitted_after:false,window_origin:'explicit_offset'})});
+ assert.equal((await execute(end,{'after-start':'20'})).code,0);
+ await assert.rejects(execute(detail(),{'before-start':'0'}));await assert.rejects(execute(detail(),{'after-start':'1'}));
+ const empty=detail({kind:'unavailable',before:null,after:null,text_bytes:0,comparison:'no_observation'});assert.match((await execute(empty)).stdout,/no retained observation/);
+});
+test('event terminal output escapes controls while JSON retains exact source strings',async()=>{
+ const value=detail({gap:true,text_bytes:12,after:side({text:'é🌲 valu\u001b',title:'Title\u001b[2J'})});
+ const human=await execute(value);assert.ok(!human.stdout.includes('\u001b'));assert.match(human.stdout,/\\u001b/);assert.match(human.stderr,/exact change time is unknown/);
+ assert.equal(JSON.parse((await execute(value,{json:true})).stdout).after.text,value.after.text);
+});
+test('event failures do not disclose upstream detail or start fallback operations',async()=>{
+ const result=await execute(Object.assign(new Error('PRIVATE_SOURCE_SECRET'),{status:403}),{json:true});assert.equal(result.code,1);assert.equal(result.calls.length,1);assert.ok(!result.stdout.includes('PRIVATE_SOURCE_SECRET'));
+});
+const script=fileURLToPath(new URL('../bin/opencrawl.mjs',import.meta.url));
+function run(args,env,cwd){return new Promise((resolve,reject)=>{const child=spawn(process.execPath,[script,...args],{env,cwd,stdio:['ignore','pipe','pipe']});let stdout='',stderr='';const timer=setTimeout(()=>child.kill('SIGKILL'),10000);child.stdout.on('data',x=>stdout+=x);child.stderr.on('data',x=>stderr+=x);child.on('error',reject);child.on('close',code=>{clearTimeout(timer);resolve({code,stdout,stderr})})});}
+test('actual CLI event command retains selected account/origin and never edits credentials',async()=>{
+ const dir=await fs.mkdtemp(path.join(os.tmpdir(),'opencrawl-event-')),calls=[];
+ const server=http.createServer((req,res)=>{calls.push({url:req.url,method:req.method,authorization:req.headers.authorization});res.setHeader('content-type','application/json');res.end(JSON.stringify(detail()));});
+ await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));const origin='http://127.0.0.1:'+server.address().port;
+ const env={...process.env};for(const name of Object.keys(env))if(name.startsWith('OPENCRAWL_'))delete env[name];env.OPENCRAWL_CONFIG_DIR=dir;
+ const config=loggedInConfig({},origin,'synthetic-event-key',{user:{id:'usr_'+'c'.repeat(32)},workspace:{id:'ws_'+'d'.repeat(32)}});await fs.writeFile(path.join(dir,'config.json'),JSON.stringify(config),{mode:0o600});
+ try{
+  const args=['research','event','rcol_one','rev_one','--account',config.activeProfile,'--json'];const result=await run(args,env,dir);assert.equal(result.code,0,result.stderr);assert.deepEqual(JSON.parse(result.stdout),detail());assert.deepEqual(calls,[{url:'/api/research/collections/rcol_one/events/rev_one?budget=16000',method:'GET',authorization:'Bearer synthetic-event-key'}]);
+  for(const extra of [['--server','https://foreign.example'],['--after-start','-1'],['--budget','256','--budget','32000']])assert.equal((await run([...args,...extra],env,dir)).code,1);
+  assert.equal(calls.length,1);assert.deepEqual(JSON.parse(await fs.readFile(path.join(dir,'config.json'),'utf8')),config);
+ }finally{server.closeAllConnections();await new Promise(resolve=>server.close(resolve));await fs.rm(dir,{recursive:true,force:true});}
+});

package/src/research-presentation.test.mjs

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import fs from 'node:fs/promises';
+import {readResearchCompletion,readResearchPresentation} from './research-completion.mjs';
+import {agentCommand,agentRequest,validateAgentDescriptor,validateAgentRun,waitAgentRun} from './research-agent.mjs';
+const f=JSON.parse(await fs.readFile(new URL('./fixtures/research-completion-v2.json',import.meta.url),'utf8'));
+const old=JSON.parse(await fs.readFile(new URL('./fixtures/research-completion-hosted.json',import.meta.url),'utf8'));
+const initial=()=>({...structuredClone(old.runs.admitted),status:'running',phase:'presenting',usage:{completion:structuredClone(f.admitted)}});
+const brief={customer:{name:'Northlight',website:'https://northlight.example/',context:''},goal:'Find documented workflow changes.',collection_ids:[],schedule_minutes:0};
+
+test('v2 create/run selection is explicit and omitted request remains byte-identical',()=>{
+ assert.equal(JSON.stringify(validateAgentDescriptor(brief)),JSON.stringify(brief));
+ assert.deepEqual(validateAgentDescriptor({...brief,research_policy:'completion_v2'}),{...brief,research_policy:'completion_v2'});
+ const args=['agent','run',initial().agent_id],options={revision:'1','request-key':'original-key-0000001'};
+ assert.deepEqual(agentRequest(args,options).body,{expected_revision:1});
+ assert.deepEqual(agentRequest(args,{...options,'research-policy':'completion_v2'}).body,{expected_revision:1,research_policy:'completion_v2'});
+ for(const policy of ['completion_v4',null,false])assert.throws(()=>agentRequest(args,{...options,'research-policy':policy}));
+});
+test('CLI v2 readers preserve finite receipt and ignore malformed presentation',()=>{
+ assert.deepEqual(readResearchCompletion(initial()).completion,f.admitted);
+ assert.deepEqual(readResearchPresentation({usage:{presentation:f.presentation}}),f.presentation);
+ for(const presentation of [{...f.presentation,raw:'PRIVATE'},{...f.presentation,calls_completed:2},{...f.presentation,known_output_tokens:12001}])assert.equal(readResearchPresentation({usage:{presentation}}),null);
+ assert.deepEqual(validateAgentRun({...initial(),usage:{presentation:{status:'PRIVATE'}}}).phase,'presenting');
+});
+test('CLI default v2 wait passes300 seconds then expires once at540 from original start',async()=>{
+ let clock=5000,calls=0;const original=initial();
+ const result=await waitAgentRun({request:async(_route,options)=>{assert.ok(options.timeout<=30000);calls++;clock+=Math.min(25000,options.timeout);return initial()}},original,{now:()=>clock,sleep:async ms=>clock+=ms});
+ assert.equal(result.wait.outcome,'timeout');assert.equal(calls,20);assert.equal(clock,545000); // original start plus540 seconds, never renewed
+});
+test('CLI explicit and malformed-policy waits keep old timeout and never replay writes',async()=>{
+ for(const [usage,timeout,expected] of [[{},undefined,12],[{completion:{policy:'completion_v2'}},undefined,12],[{completion:f.admitted},300,12],[{completion:f.admitted},1,1]]){
+  let clock=0,calls=0;const run={...initial(),usage};
+  const result=await waitAgentRun({request:async(_route,options)=>{assert.equal(options.method,undefined);calls++;clock+=Math.min(25000,options.timeout);return run}},run,{...(timeout===undefined?{}:{timeout}),now:()=>clock,sleep:async ms=>clock+=ms});
+  assert.equal(result.wait.outcome,'timeout');assert.equal(calls,expected);
+ }
+});
+test('human fallback is one fixed notice; raw JSON, all gaps, findings and quotes remain intact',async()=>{
+ const run=structuredClone(old.runs.repaired);run.usage.presentation=structuredClone(f.presentation);run.gaps=Array.from({length:5},(_,i)=>`Original gap ${i+1}.`);
+ const invoke=async json=>{let stdout='',stderr='',calls=0;const code=await agentCommand(['agent-run',run.agent_id,run.id],{json},{request:async()=>{calls++;return run}},{stdout:x=>stdout+=x,stderr:x=>stderr+=x});return {stdout,stderr,calls,code}};
+ const json=await invoke(true);assert.deepEqual(JSON.parse(json.stdout),run);assert.equal(json.calls,1);
+ const human=await invoke(false);assert.equal((human.stdout.match(/Summary:/g)||[]).length,1);
+ for(const text of [...run.gaps,...run.findings.flatMap(v=>[v.claim,...v.qualifiers,...v.citations.map(c=>c.quote)])])assert.ok(human.stdout.includes(text));
+ run.usage.presentation.status='skipped_no_eligible';assert.equal((await invoke(false)).stdout.includes('Summary:'),false);
+ run.usage.presentation.raw='PRIVATE';assert.equal((await invoke(false)).stdout.includes('Summary:'),false);
+});
+
+test('actual admitted presenting reviewed and fallback public states are unchanged through CLI JSON',async()=>{
+ const actual=JSON.parse(await fs.readFile(new URL('./fixtures/research-presentation-hosted.json',import.meta.url),'utf8'));
+ assert.equal(actual.presenting.phase,'synthesizing');
+ for(const run of Object.values(actual)){
+  let stdout='',calls=0;const before=JSON.stringify(run);
+  const code=await agentCommand(['agent-run',run.agent_id,run.id],{json:true},{request:async()=>{calls++;return run}},{stdout:x=>stdout+=x,stderr:()=>{}});
+  assert.equal(code,0);assert.deepEqual(JSON.parse(stdout),run);assert.equal(calls,1);assert.equal(JSON.stringify(run),before);
+  assert.deepEqual(readResearchCompletion(run).completion,run.usage.completion);assert.deepEqual(readResearchPresentation(run),run.usage.presentation??null);
+ }
+});