@getopencrawl/cli 0.1.1 → 0.2.0

package/src/research-agent.mjs

@@ -1,164 +0,0 @@
-import {readResearchCompletion,readResearchPresentation} from './research-completion.mjs';
-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,settle,transient,withInterrupt} from './jobs.mjs';
-import {displayLine,displayText} from './display.mjs';
-
-const ROOT='/api/research/agents',ACTIVE=new Set(['queued','running']);
-const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
-const text=(v,max,min=0)=>typeof v==='string'&&Array.from(v).length>=min&&Array.from(v).length<=max&&!/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v);
-const integer=(v,min=0,max=Number.MAX_SAFE_INTEGER)=>Number.isSafeInteger(v)&&v>=min&&v<=max;
-const stamp=v=>typeof v==='string'&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|\+00:00)$/.test(v)&&Number.isFinite(Date.parse(v))&&new Date(v).toISOString().slice(0,19)===v.slice(0,19);
-const fields=(v,keys)=>Object.keys(v).every(key=>keys.includes(key));
-function canonicalWebsite(value){if(/[\\\s\u0000-\u001f\u007f]/.test(value)||/%(?![0-9a-f]{2})/i.test(value))throw new Error('Use a valid public website URL.');const u=new URL(value);u.hash='';return new URL(u.href.replace(/%([0-9a-f]{2})/gi,(_all,hex)=>{const ch=String.fromCharCode(parseInt(hex,16));return /^[A-Za-z0-9._~-]$/.test(ch)?ch:'%'+hex.toUpperCase()})).href;}
-function publicUrl(v){if(!text(v,2048,1))return false;try{const u=new URL(v);return ['http:','https:'].includes(u.protocol)&&!u.username&&!u.password&&!!u.hostname}catch{return false}}
-function pageEvidence(cite){
- if(cite.source_kind!=='web_page')return !Object.hasOwn(cite,'page');
- const p=cite.page;
- return object(p)&&fields(p,['requested_url','final_url','body_sha256','start','end','total_chars','extractor'])&&publicUrl(p.requested_url)&&publicUrl(p.final_url)&&p.final_url===cite.url&&typeof p.body_sha256==='string'&&/^[0-9a-f]{64}$/.test(p.body_sha256)&&integer(p.start,0,131071)&&integer(p.end,1,131072)&&integer(p.total_chars,1,131072)&&p.start<p.end&&p.end<=p.total_chars&&p.end-p.start<=16000&&typeof cite.end==='number'&&cite.end<=p.end-p.start&&p.extractor==='public-static-v3';
-}
-const invalid=()=>{throw new Error('Server returned invalid or out-of-scope saved research findings. No result was emitted.');};
-const feedbackRatings=['useful','irrelevant','incorrect','outdated'];
-const feedbackNote=value=>value===null||text(value,1000)&&!value.includes('\u0000')&&Buffer.byteLength(value)<=4096;
-function confirmedReadFailure(error,request){
- if((request.method??'GET')!=='GET'||!Number.isInteger(error?.status))return null;
- 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. 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;
-}
-export function validateAgentFeedback(value,agentId,runId,findingId){
- if(!object(value)||!fields(value,['agent_id','run_id','finding_id','feedback'])||value.agent_id!==agentId||value.run_id!==runId||value.finding_id!==findingId||!object(value.feedback))invalid();
- const f=value.feedback;if(!fields(f,['version','revision','state','rating','note','updated_at'])||f.version!==1||!integer(f.revision)||!feedbackNote(f.note)||Buffer.byteLength(JSON.stringify(value))>8192)invalid();
- if(f.state==='absent'){if(f.revision!==0||f.rating!==null||f.note!==null||f.updated_at!==null)invalid()}
- else if(f.state==='deleted'){if(f.revision<1||f.rating!==null||f.note!==null||!stamp(f.updated_at))invalid()}
- else if(f.state==='active'){if(f.revision<1||!feedbackRatings.includes(f.rating)||!stamp(f.updated_at))invalid()}
- else invalid();return value;
-}
-export function validateAgentSource(value,agentId,runId,sourceId){
- if(!object(value)||!fields(value,['agent_id','run_id','source'])||value.agent_id!==agentId||value.run_id!==runId||!object(value.source))invalid();
- const source=value.source;
- if(!fields(source,['id','url','title','text','body_sha256','observed_at','published_at','source_kind','collection_id','document_id','version_id','page'])||source.id!==sourceId||!text(source.id,80,1)||!publicUrl(source.url)||!text(source.title,2048,1)||!text(source.text,16000,1)||!source.text.trim()||source.text.includes('\u0000')||!stamp(source.observed_at)||source.published_at!==null&&!text(source.published_at,100,1)||!['indexed','web_page'].includes(source.source_kind)||!pageEvidence({...source,end:Array.from(source.text).length})||typeof source.body_sha256!=='string'||!/^[0-9a-f]{64}$/.test(source.body_sha256))invalid();
- for(const key of ['collection_id','document_id','version_id'])if(source.source_kind==='indexed'?!text(source[key],200,1):source[key]!==null)invalid();
- if(source.source_kind==='web_page'&&source.page.end-source.page.start!==Array.from(source.text).length)invalid();
- if(Buffer.byteLength(JSON.stringify(value))>131072||createHash('sha256').update(source.text,'utf8').digest('hex')!==source.body_sha256)invalid();
- return value;
-}
-export function validateAgentDescriptor(value){
- if(!object(value)||!fields(value,['customer','goal','collection_ids','schedule_minutes','research_policy'])||!object(value.customer)||!fields(value.customer,['name','website','context'])||!text(value.customer.name,200,1)||!value.customer.name.trim()||!publicUrl(value.customer.website)||!text(value.customer.context??'',4000)||!text(value.goal,4000,1)||!value.goal.trim()||value.schedule_minutes!==undefined&&value.schedule_minutes!==0||!Array.isArray(value.collection_ids??[])||(value.collection_ids??[]).length>8||!(value.collection_ids??[]).every(v=>text(v,200,1))||new Set(value.collection_ids??[]).size!==(value.collection_ids??[]).length)throw new Error('Agent JSON must contain a customer name and public website, a goal, optional context and up to eight unique collection_ids; schedule_minutes must be 0.');
- if(Object.hasOwn(value,'research_policy')&&!['completion_v1','completion_v2','completion_v3'].includes(value.research_policy))throw new Error('research_policy must be completion_v1, completion_v2 or completion_v3 when explicitly supplied.');
- const result={customer:{name:value.customer.name.trim(),website:canonicalWebsite(value.customer.website),context:value.customer.context??''},goal:value.goal.trim(),collection_ids:value.collection_ids??[],schedule_minutes:0,...(Object.hasOwn(value,'research_policy')?{research_policy:value.research_policy}:{})};if(Buffer.byteLength(JSON.stringify(result))>32768)throw new Error('The research brief exceeds 32 KiB.');return result;
-}
-export function validateAgentRun(value,agentId=value?.agent_id,runId=value?.id){
- if(!object(value)||!fields(value,['id','agent_id','agent_revision','status','phase','created_at','started_at','finished_at','outcome','findings','gaps','usage','error'])||!text(value.id,200,1)||value.id!==runId||!text(value.agent_id,200,1)||value.agent_id!==agentId||!integer(value.agent_revision,1)||!['queued','running','completed','partial','needs_input','failed','unknown','cancelled'].includes(value.status)||!['queued','researching','synthesizing','presenting','finished'].includes(value.phase)||!stamp(value.created_at)||value.started_at!==null&&!stamp(value.started_at)||value.finished_at!==null&&!stamp(value.finished_at)||!['findings','no_supported_findings','needs_input',null].includes(value.outcome)||!Array.isArray(value.findings)||value.findings.length>5||!Array.isArray(value.gaps)||value.gaps.length>5||!value.gaps.every(v=>text(v,500,1))||!object(value.usage)||Buffer.byteLength(JSON.stringify(value.usage))>16384||value.error!==null&&(!object(value.error)||!text(value.error.code,100,1)||!text(value.error.message,1000,1)))invalid();
- const seen=new Set();for(const finding of value.findings){if(!object(finding)||!fields(finding,['id','claim','relevance','qualifiers','citations'])||!text(finding.id,200,1)||seen.has(finding.id)||!text(finding.claim,1500,1)||!text(finding.relevance,1500,1)||!Array.isArray(finding.qualifiers)||finding.qualifiers.length>5||!finding.qualifiers.every(v=>text(v,300,1))||!Array.isArray(finding.citations)||finding.citations.length<1||finding.citations.length>3)invalid();seen.add(finding.id);
-  for(const cite of finding.citations){if(!object(cite)||!fields(cite,['id','url','title','quote','start','end','body_sha256','observed_at','published_at','source_kind','collection_id','document_id','version_id','page'])||!text(cite.id,80,1)||!publicUrl(cite.url)||!text(cite.title,2048)||!text(cite.quote,1200,1)||!integer(cite.start,0,16000)||!integer(cite.end,1,16000)||cite.end-cite.start!==Array.from(cite.quote).length||typeof cite.body_sha256!=='string'||!/^[0-9a-f]{64}$/.test(cite.body_sha256)||!stamp(cite.observed_at)||cite.published_at!==null&&!text(cite.published_at,100,1)||!['web_search','indexed','web_page'].includes(cite.source_kind)||!pageEvidence(cite))invalid();for(const key of ['collection_id','document_id','version_id'])if(cite.source_kind==='indexed'?!text(cite[key],200,1):cite[key]!==null)invalid();}
- }
- if((value.outcome==='findings')!==Boolean(value.findings.length)||ACTIVE.has(value.status)&&(value.phase==='finished'||value.outcome!==null||value.findings.length||value.finished_at!==null)||!ACTIVE.has(value.status)&&value.phase!=='finished'||Buffer.byteLength(JSON.stringify({findings:value.findings,gaps:value.gaps}))>32768)invalid();return value;
-}
-export function validateResearchAgent(value,id=value?.id){if(!object(value)||!fields(value,['id','customer','goal','collection_ids','revision','status','schedule_minutes','created_at','updated_at','latest_run'])||!text(value.id,200,1)||value.id!==id||!integer(value.revision,1)||!['active','paused'].includes(value.status)||![0,1440].includes(value.schedule_minutes)||!stamp(value.created_at)||!stamp(value.updated_at)||!text(value.customer?.context,4000))invalid();try{validateAgentDescriptor({customer:value.customer,goal:value.goal,collection_ids:value.collection_ids,schedule_minutes:0})}catch{invalid()}if(value.latest_run!==null)validateAgentRun(value.latest_run,value.id);return value;}
-export function validateAgentSchedule(value,agentId){
- if(!object(value)||!fields(value,['agent_id','revision','enabled','schedule_minutes','next_scheduled_at','blocked_reason','blocked_run_id','deferred_reason'])||value.agent_id!==agentId||!integer(value.revision)||typeof value.enabled!=='boolean'||value.schedule_minutes!==(value.enabled?1440:0)||!['unknown','failed','needs_input','cancelled','access_changed','agent_paused',null].includes(value.blocked_reason)||!['capacity','daily_budget','storage','run_active','history_capacity',null].includes(value.deferred_reason)||value.blocked_run_id!==null&&!text(value.blocked_run_id,200,1)||value.next_scheduled_at!==null&&!stamp(value.next_scheduled_at))invalid();
- if((!value.enabled||value.blocked_reason!==null)&&value.deferred_reason!==null||!value.enabled&&(value.next_scheduled_at!==null||value.blocked_reason!==null||value.blocked_run_id!==null)||value.enabled&&(value.revision===0||(value.blocked_reason===null)!==(value.next_scheduled_at!==null))||value.blocked_reason===null&&value.blocked_run_id!==null)invalid();
- return value;
-}
-export function validateAgentRepeats(value,agentId,runId){
- if(!object(value)||!fields(value,['agent_id','run_id','status','items'])||value.agent_id!==agentId||value.run_id!==runId||!['available','not_assessed'].includes(value.status)||!Array.isArray(value.items)||value.items.length>5||value.status==='not_assessed'&&value.items.length)invalid();
- const seen=new Set();for(const item of value.items){
-  if(!object(item)||!fields(item,['finding_id','classification','first_seen_run_id','first_seen_finding_id'])||!text(item.finding_id,200,1)||seen.has(item.finding_id)||!text(item.first_seen_run_id,200,1)||!text(item.first_seen_finding_id,200,1)||!['first_seen','exact_repeat'].includes(item.classification))invalid();
-  const same=item.first_seen_run_id===runId&&item.first_seen_finding_id===item.finding_id;if((item.classification==='first_seen')!==same||item.classification==='exact_repeat'&&item.first_seen_run_id===runId)invalid();seen.add(item.finding_id);
- }
- return value;
-}
-export function validateAgentReceipt(value,id){if(!object(value)||!fields(value,['agent','run','replayed'])||typeof value.replayed!=='boolean')invalid();const agent=validateResearchAgent(value.agent,id??value.agent?.id),run=validateAgentRun(value.run,agent.id);if(agent.revision!==run.agent_revision||agent.latest_run?.id!==run.id)invalid();return value;}
-function key(value){if(typeof value!=='string'||!/^[A-Za-z0-9_-]{16,128}$/.test(value))throw new Error('Retain a random 16–128 character --request-key for this exact research request.');return value;}
-export function agentRequest(rest,options){
- if(rest[0]==='agent'&&rest[1]==='feedback'){
-  const [, ,id,runId,findingId,action='show',...extra]=rest;
-  identifier(id,'agent');identifier(runId,'run');identifier(findingId,'finding');
-  if(extra.length||!['show','set','delete'].includes(action))throw new Error('Use research agent feedback AGENT_ID RUN_ID FINDING_ID [show|set|delete].');
-  allowedOptions(options,action==='show'?[]:action==='set'?['revision','rating','note']:['revision'],'research agent feedback');
-  const route=`${ROOT}/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/findings/${encodeURIComponent(findingId)}/feedback`,base={command:'feedback',id,runId,findingId,action,route};
-  if(action==='show')return base;
-  const revision=decimal(options.revision,'revision',0,Number.MAX_SAFE_INTEGER);
-  if(action==='delete')return {...base,revision,method:'DELETE',route:route+`?expected_revision=${revision}`};
-  if(!feedbackRatings.includes(options.rating)||!feedbackNote(options.note??null))throw new Error('Use --rating useful|irrelevant|incorrect|outdated and an optional note of at most 1000 Unicode characters.');
-  return {...base,revision,method:'PUT',body:{expected_revision:revision,rating:options.rating,note:options.note??null}};
- }
- if(rest[0]==='agent'&&rest[1]==='source'){
-  allowedOptions(options,[],'research agent source');if(rest.length!==5)throw new Error('Use research agent source AGENT_ID RUN_ID SOURCE_ID.');
-  const id=identifier(rest[2],'agent'),runId=identifier(rest[3],'run'),sourceId=identifier(rest[4],'source');return {command:'source',id,runId,sourceId,route:`${ROOT}/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/sources/${encodeURIComponent(sourceId)}`};
- }
- if(rest[0]==='agent'&&rest[1]==='runs'){
-  allowedOptions(options,['limit','cursor'],'research agent runs');if(rest.length!==3)throw new Error('Use research agent runs AGENT_ID [--limit N] [--cursor CURSOR].');
-  const id=identifier(rest[2],'agent'),limit=decimal(options.limit,'limit',1,100,25),query=new URLSearchParams({limit});
-  if(options.cursor!==undefined){if(typeof options.cursor!=='string'||!/^[\x21-\x7e]{1,512}$/.test(options.cursor))throw new Error('Use the returned opaque research history cursor.');query.set('cursor',options.cursor)}
-  return {command:'runs',id,limit,cursor:options.cursor,route:`${ROOT}/${encodeURIComponent(id)}/runs?${query}`};
- }
- if(rest[0]==='agent'&&rest[1]==='schedule'){
-  const [, ,id,action='show',...extra]=rest;identifier(id,'agent');if(extra.length||!['show','daily','pause','resume'].includes(action))throw new Error('Use research agent schedule AGENT_ID [show|daily|pause|resume].');allowedOptions(options,action==='show'?[]:['revision'],'research agent schedule');
-  return {command:'schedule',id,route:`${ROOT}/${encodeURIComponent(id)}/schedule`,...(action==='show'?{}:{method:'PATCH',body:{expected_revision:decimal(options.revision,'revision',0,Number.MAX_SAFE_INTEGER),enabled:action!=='pause'}})};
- }
- if(rest[0]==='agent'&&rest[1]==='repeats'){
-  allowedOptions(options,[],'research agent repeats');if(rest.length!==4)throw new Error('Use research agent repeats AGENT_ID RUN_ID.');const id=identifier(rest[2],'agent'),runId=identifier(rest[3],'run');return {command:'repeats',id,runId,route:`${ROOT}/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/repeats`};
- }
- if(rest[0]==='agent-run'){
-  allowedOptions(options,['wait','timeout'],'research agent-run');if(rest.length!==3)throw new Error('Use research agent-run AGENT_ID RUN_ID.');
-  const id=identifier(rest[1],'agent'),runId=identifier(rest[2],'run');if(options.timeout!==undefined&&!options.wait)throw new Error('--timeout requires --wait.');
-  return {command:'agent-run',id,runId,route:`${ROOT}/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}`,wait:!!options.wait,timeout:decimal(options.timeout,'timeout',1,3600,300)};
- }
- const [,command,id,...extra]=rest,allowed={create:['file','request-key','wait','timeout'],list:['limit','cursor'],show:[],run:['revision','request-key','wait','timeout','research-policy'],pause:['revision'],resume:['revision'],receipt:['operation','request-key']};
- if(!Object.hasOwn(allowed,command))throw new Error('Choose research agent create, list, show, run, pause, resume or receipt.');allowedOptions(options,allowed[command],'research agent');
- if(extra.length||['create','list','receipt'].includes(command)&&id!==undefined)throw new Error('Unexpected research agent argument.');
- if(options.timeout!==undefined&&!options.wait)throw new Error('--timeout requires --wait.');
- const base={command,wait:!!options.wait,timeout:decimal(options.timeout,'timeout',1,3600,300)};
- if(command==='create'){if(!text(options.file,4096,1))throw new Error('Provide --file with the research brief JSON.');return {...base,route:ROOT,method:'POST',file:options.file,key:key(options['request-key'])};}
- if(command==='list'){const limit=decimal(options.limit,'limit',1,100,25),q=new URLSearchParams({limit});if(options.cursor!==undefined){if(!text(options.cursor,512,1))throw new Error('Use the returned bounded cursor.');q.set('cursor',options.cursor)}return {...base,limit,route:ROOT+'?'+q};}
- if(command==='receipt'){if(options.operation!=='create'&&!/^run:ragent_[0-9a-f]{32}$/.test(options.operation??''))throw new Error('--operation must be create or run:AGENT_ID.');return {...base,route:ROOT+'/receipts/by-key?operation='+encodeURIComponent(options.operation),key:key(options['request-key']),id:options.operation==='create'?undefined:options.operation.slice(4)};}
- identifier(id,'agent');const route=ROOT+'/'+encodeURIComponent(id);
- if(command==='show')return {...base,id,route};
- const revision=decimal(options.revision,'revision',1,Number.MAX_SAFE_INTEGER);
- if(command==='run'){if(Object.hasOwn(options,'research-policy')&&!['completion_v1','completion_v2','completion_v3'].includes(options['research-policy']))throw new Error('--research-policy must be completion_v1, completion_v2 or completion_v3 when explicitly supplied.');return {...base,id,route:route+'/runs',method:'POST',body:{expected_revision:revision,...(Object.hasOwn(options,'research-policy')?{research_policy:options['research-policy']}:{})},key:key(options['request-key'])};}
- 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),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);
- let value;try{value=await client.request(request.route,{method:request.method,body:request.body,idempotencyKey:request.key,maxResponseBytes:request.command==='source'?131072:request.command==='runs'?1048576:4*1024*1024});
-  if(request.command==='runs'){
-   if(!object(value)||!fields(value,['items','next_cursor','has_more'])||!Array.isArray(value.items)||value.items.length>request.limit||typeof value.next_cursor!=='string'||!/^[\x21-\x7e]{1,512}$/.test(value.next_cursor)||typeof value.has_more!=='boolean'||value.has_more&&!value.items.length||request.cursor!==undefined&&(value.items.length?value.next_cursor===request.cursor:value.next_cursor!==request.cursor)||Buffer.byteLength(JSON.stringify(value))>1048576)invalid();
-   const seen=new Set();for(const item of value.items){const run=validateAgentRun(item,request.id);if(seen.has(run.id))invalid();seen.add(run.id)}
-  }
-  else if(request.command==='list'){if(!object(value)||!Array.isArray(value.items)||value.items.length>request.limit||value.next_cursor!==null&&!text(value.next_cursor,512,1))invalid();value.items.forEach(item=>validateResearchAgent(item));}
-  else if(['create','run','receipt'].includes(request.command)){validateAgentReceipt(value,request.id);if(request.command==='create'&&(value.agent.revision!==1||value.agent.schedule_minutes!==0||value.agent.goal!==request.body.goal||['name','website','context'].some(k=>value.agent.customer[k]!==request.body.customer[k])||JSON.stringify(value.agent.collection_ids)!==JSON.stringify(request.body.collection_ids)))invalid();if(request.command==='run'&&value.run.agent_revision!==request.body.expected_revision)invalid();}
-  else if(request.command==='schedule'){validateAgentSchedule(value,request.id);if(request.body&&(value.enabled!==request.body.enabled||![request.body.expected_revision,request.body.expected_revision+1].includes(value.revision)))invalid();}
-  else if(request.command==='feedback'){
-   validateAgentFeedback(value,request.id,request.runId,request.findingId);const f=value.feedback;
-   if(request.action!=='show'&&![request.revision,request.revision+1].includes(f.revision))invalid();
-   if(request.action==='set'&&(f.state!=='active'||f.rating!==request.body.rating||f.note!==request.body.note)||request.action==='delete'&&f.state==='active')invalid();
-  }
-  else if(request.command==='source')validateAgentSource(value,request.id,request.runId,request.sourceId);
-  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.'+(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;}
- if(request.command==='schedule'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else stdout(`Agent: ${displayLine(value.agent_id)}\nSchedule revision: ${value.revision}\nDaily research: ${value.enabled?'enabled':'disabled'}\nNext scheduled: ${displayLine(value.next_scheduled_at??'none')}\nBlocked: ${displayLine(value.blocked_reason??'no')}\nDeferred: ${displayLine(value.deferred_reason??'no')}\n`);return 0;}
- if(request.command==='repeats'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else{stdout(`Run: ${displayLine(value.run_id)}\nExact-repeat assessment: ${displayLine(value.status)}\n`);for(const item of value.items)stdout(`${displayLine(item.finding_id)}\t${displayLine(item.classification)}\tfirst seen ${displayLine(item.first_seen_run_id)} / ${displayLine(item.first_seen_finding_id)}\n`);stdout('Exact repetition is not a judgment of business novelty; all saved findings remain available.\n');}return 0;}
- if(request.command==='list'){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else{for(const agent of value.items)stdout(`${displayLine(agent.id)}\tr${agent.revision}\t${displayLine(agent.status)}\t${displayLine(agent.customer.name)}\n`);if(value.next_cursor)stderr('Next cursor: '+displayLine(value.next_cursor)+'\n');}return 0;}
- if(['show','pause','resume'].includes(request.command)){if(options.json)stdout(JSON.stringify(value,null,2)+'\n');else{stdout(`Agent: ${displayLine(value.id)}\nCustomer: ${displayLine(value.customer.name)}\nGoal: ${displayText(value.goal)}\nRevision: ${value.revision}\nStatus: ${displayLine(value.status)}\n`);if(value.latest_run)renderRun(value.latest_run,stdout);}return 0;}
- let run=request.command==='agent-run'?value:value.run,output=value;
- if(request.wait){const waited=await withInterrupt(signal=>waitAgentRun(client,run,{...(options.timeout===undefined?{}:{timeout:request.timeout}),signal}));run=waited.run;output=request.command==='agent-run'?waited:{...value,...waited};}
- if(options.json)stdout(JSON.stringify(output,null,2)+'\n');else{renderRun(run,stdout);if(value.replayed)stderr('Recovered the original admission receipt; read its run for current findings.\n');if(request.key)stderr('Original request key: '+request.key+'\n');}
- if(output.wait&&!['completed','partial'].includes(output.wait.outcome)){if(output.wait.error&&!options.json)stderr(output.wait.error.message+'\n');stderr('Follow the same agent and run to continue. Waiting does not cancel server work.\n');return 1;}
- return request.wait||request.command==='agent-run'?run.status==='completed'?0:run.status==='partial'?2:ACTIVE.has(run.status)&&!request.wait?0:1:0;
-}

package/src/research-agent.test.mjs

@@ -1,231 +0,0 @@
-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.mjs

@@ -1,3 +0,0 @@
-import {createHash} from 'node:crypto';
-import {readAnswerContract} from './answer-contract.mjs';
-export const readResearchAnswerContract=run=>readAnswerContract(run,text=>createHash('sha256').update(text,'utf8').digest('hex'));

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

@@ -1,14 +0,0 @@
-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.mjs

@@ -1,7 +0,0 @@
-import {createHash} from 'node:crypto';
-import {readResearchAnswerContract} from './research-answer-contract.mjs';
-import {readAnswerView} from './answer-view.mjs';
-export function readResearchAnswerView(run){
- if(!Object.hasOwn(run.usage,'answer_view'))return {state:'absent',view:null,sections:[]};
- return readAnswerView(run,readResearchAnswerContract(run),text=>createHash('sha256').update(text,'utf8').digest('hex'));
-}

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

@@ -1,27 +0,0 @@
-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');
-});