@getopencrawl/cli 0.0.0-stage → 0.1.0

package/src/capture.mjs

@@ -0,0 +1,273 @@
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { configDir, createClient } from './client.mjs';
+import { allowedOptions, decimal } from './jobs.mjs';
+import { displayLine } from './display.mjs';
+
+export const CAPTURE_HELP = `OpenCrawl · capture new project conversations
+
+  opencrawl install claude-code|codex --capture
+  opencrawl capture status --provider claude-code|codex [--json]
+  opencrawl capture flush --provider claude-code|codex [--timeout 10] [--json]
+  opencrawl capture pause|resume --provider claude-code|codex
+
+The current project is the default; --project DIRECTORY selects an installed
+project explicitly. New user prompts and final assistant messages are private.
+No transcript files, old chats, tools, reasoning, or other projects are read.
+Status reads saved receipts and current server readiness. Flush explicitly
+replays only immutable queued events using server idempotence, for 1–60 seconds.
+Unknown delivery is never called indexed. Conflicts/deleted sessions stay blocked.
+Pause stops new local capture; resume captures future events, not missed history.
+Persist the owner-only OpenCrawl configuration directory in disposable sandboxes.
+Global options: --account PROFILE_ID --server URL --config-dir DIRECTORY --json
+Environment-key install: --credential-env NAME (name only; key never in settings).
+`;
+export const AGENT_OPTIONS = ['credential-env','expect-user','expect-workspace'];
+const PROVIDERS = ['claude-code','codex'];
+const MAX_STORE = 8 * 1024 * 1024, MAX_CONTENT = 64 * 1024, MAX_SESSIONS = 100, MAX_EVENTS = 20000;
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const fail = message => { throw new Error(message); };
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\u0000-\u0020\u007f]/.test(value);
+const user = value => /^usr_[a-f0-9]{32}$/.test(value || '');
+const workspace = value => /^ws_[a-f0-9]{32}$/.test(value || '');
+const same = (a,b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Explicit environment credentials require a destination and durable identity pins. */
+export async function agentClient(options, { installing = false } = {}) {
+  if (options['credential-env'] === undefined) {
+    if (options['expect-user'] !== undefined || options['expect-workspace'] !== undefined) fail('Identity pins require --credential-env.');
+    return createClient(options);
+  }
+  const name = options['credential-env'];
+  if (!/^[A-Z][A-Z0-9_]{1,79}$/.test(name) || !options.server || options.account) fail('Environment-key setup requires an explicit --server, a variable name, and no saved --account.');
+  if (!installing && (!user(options['expect-user']) || !workspace(options['expect-workspace']))) fail('Environment-key agent setup needs verified identity pins. Rerun the installer in this runtime.');
+  const token = process.env[name];
+  if (!token) fail('The configured credential environment variable is missing. No saved key was substituted.');
+  const client = await createClient({ server: options.server, token });
+  client.expectedIdentity = installing ? null : { user_id: options['expect-user'], workspace_id: options['expect-workspace'] };
+  return client;
+}
+export function bindingIdentity(client) {
+  const value = client.expectedIdentity || (client.profile && { user_id: client.profile.userId, workspace_id: client.profile.workspaceId });
+  if (!client.configured || !value || !user(value.user_id) || !workspace(value.workspace_id)) fail('Capture requires a verified saved account or an installed environment-key identity.');
+  return { server: client.baseUrl, ...value };
+}
+export async function verifyAgentIdentity(client, timeout = 2000) {
+  const result = await client.request('/api/auth/me', { timeout, maxResponseBytes: 128 * 1024 });
+  const actual = { user_id: result?.user?.id, workspace_id: result?.workspace?.id };
+  if (!user(actual.user_id) || !workspace(actual.workspace_id)) fail('The server did not return a valid account identity.');
+  const expected = client.expectedIdentity || (client.profile && { user_id: client.profile.userId, workspace_id: client.profile.workspaceId });
+  if (expected && !same(actual, expected)) fail('The credential does not match the installed user and workspace. Nothing was sent.');
+  return { server: client.baseUrl, ...actual };
+}
+async function privateDirectory(directory) {
+  await fs.mkdir(directory,{recursive:true,mode:0o700});
+  const stat=await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || typeof process.getuid==='function' && stat.uid!==process.getuid()) fail('Capture state must be in a directory owned by this user, without symbolic links.');
+  await fs.chmod(directory,0o700);
+}
+async function projectScope(client, provider, project) {
+  if (!PROVIDERS.includes(provider)) fail('Choose --provider claude-code or codex.');
+  const root=await fs.realpath(project || process.cwd());
+  if (!(await fs.stat(root)).isDirectory()) fail('Capture project must be a directory.');
+  return { ...bindingIdentity(client), provider, project: root };
+}
+async function storage(scope, action, { initialize=false }={}) {
+  const root=path.resolve(configDir());await privateDirectory(root);
+  const directory=path.join(root,'capture');await privateDirectory(directory);
+  const name=hash(JSON.stringify(scope)),file=path.join(directory,name+'.json'),lockfile=path.join(directory,name+'.lock');
+  let lock;
+  const until=Date.now()+700;
+  while (!lock) {
+    try { lock=await fs.open(lockfile,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);await lock.writeFile(String(process.pid)); }
+    catch (error) { if(error.code!=='EEXIST')throw error;if(Date.now()>=until)fail('Capture is busy or has a stale lock. Inspect capture status; remove its lock only after confirming the previous process stopped.');await new Promise(resolve=>setTimeout(resolve,25)); }
+  }
+  try {
+    let state,handle;
+    try {
+      handle=await fs.open(file,constants.O_RDONLY|constants.O_NOFOLLOW);const stat=await handle.stat();
+      if(!stat.isFile()||stat.size>MAX_STORE||stat.mode&0o077||typeof process.getuid==='function'&&stat.uid!==process.getuid())fail('Capture state must be an owner-only bounded regular file.');
+      try { state=JSON.parse(await handle.readFile('utf8')); } catch { fail('Capture state is invalid. Preserve it before repair; no events were sent.'); }
+    } catch(error) {
+      if(error.code!=='ENOENT')throw error;
+      if(!initialize)fail('Capture is not configured for this project and account. Run install TARGET --capture here.');
+      if((await fs.readdir(directory)).filter(value=>/^[a-f0-9]{64}\.json$/.test(value)).length>=64)fail('Capture is limited to 64 project/account configurations. Preserve existing state before starting another.');
+      state={version:1,scope,paused:false,sessions:[],configured_at:new Date().toISOString()};
+    } finally { await handle?.close(); }
+    validateState(state,scope);
+    const save=async()=>{
+      const encoded=JSON.stringify(state);if(Buffer.byteLength(encoded)>MAX_STORE)fail('Capture spool reached its 8 MiB limit. Flush or review queued events; no content was silently dropped.');
+      const temp=file+'.'+crypto.randomUUID()+'.tmp';let output;
+      try { output=await fs.open(temp,'wx',0o600);await output.writeFile(encoded);await output.sync();await output.close();output=null;await fs.rename(temp,file);
+        if(process.platform!=='win32'){const dir=await fs.open(directory,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);try{await dir.sync();}finally{await dir.close();}} }
+      finally {await output?.close();await fs.unlink(temp).catch(error=>{if(error.code!=='ENOENT')throw error;});}
+    };
+    return await action(state,save);
+  } finally {await lock.close();await fs.unlink(lockfile);}
+}
+function validateState(state,scope) {
+  if(state?.version!==1||!same(state.scope,scope)||typeof state.paused!=='boolean'||!Array.isArray(state.sessions)||state.sessions.length>MAX_SESSIONS)fail('Capture binding or state is invalid. No events were sent.');
+  let count=0;
+  for(const session of state.sessions) {
+    if(!identifier(session.id)||!identifier(session.remote_id)||!Array.isArray(session.events)||!Number.isSafeInteger(session.next)||session.next<0||!Array.isArray(session.turns))fail('Capture session state is invalid.');
+    const ids=new Set(),sequences=new Set();
+    for(const event of session.events) {
+      if(!identifier(event.id)||ids.has(event.id)||!Number.isSafeInteger(event.sequence)||event.sequence<0||event.sequence>=session.next||sequences.has(event.sequence)||!['user','assistant'].includes(event.role)||!['queued','acknowledged'].includes(event.state)||!/^[a-f0-9]{64}$/.test(event.hash)||!Number.isInteger(event.attempts)||event.attempts<0)fail('Capture event state is invalid.');
+      if(event.state==='queued'&&(typeof event.content!=='string'||!event.content.trim()||Buffer.byteLength(event.content)>MAX_CONTENT||hash(event.content)!==event.hash))fail('Queued capture content is invalid.');
+      ids.add(event.id);sequences.add(event.sequence);count++;
+    }
+  }
+  if(count>MAX_EVENTS)fail('Capture state exceeds its event limit.');
+}
+export async function configureCapture(client,provider,project) {
+  const scope=await projectScope(client,provider,project);
+  await storage(scope,async(state,save)=>{await save();},{initialize:true});return scope;
+}
+function safeIssue(error) {
+  const status=error?.status;
+  return ({401:'authorization_required',403:'authorization_required',409:'event_conflict',410:'session_deleted',413:'capacity_exceeded',422:'invalid_event',429:'temporarily_unavailable',507:'storage_unavailable'})[status] || 'delivery_unconfirmed';
+}
+const permanent = issue => ['event_conflict','session_deleted','invalid_event','capacity_exceeded'].includes(issue);
+export function validateCaptureReceipt(value,batchCount=null) {
+  if(!value||typeof value.document_id!=='string'||!/^doc_[a-f0-9]{32}$/.test(value.document_id)||value.lexical_ready!==true||typeof value.semantic_ready!=='boolean'||!Number.isSafeInteger(value.event_count)||value.event_count<1||!['ready','pending','unavailable'].includes(value.semantic?.status)||!Number.isSafeInteger(value.semantic?.indexed_chunks)||!Number.isSafeInteger(value.semantic?.total_chunks)||value.semantic.indexed_chunks<0||value.semantic.total_chunks<value.semantic.indexed_chunks)fail('Capture acknowledgement is invalid; queued events were preserved.');
+  if(batchCount!==null&&(!Number.isSafeInteger(value.accepted_events)||!Number.isSafeInteger(value.replayed_events)||value.accepted_events<0||value.replayed_events<0||value.accepted_events+value.replayed_events!==batchCount))fail('Capture acknowledgement did not account for this exact event batch.');
+  return {document_id:value.document_id,lexical_ready:true,semantic_ready:value.semantic_ready,semantic:{status:value.semantic.status,indexed_chunks:value.semantic.indexed_chunks,total_chunks:value.semantic.total_chunks},event_count:value.event_count,observed_at:new Date().toISOString()};
+}
+function enqueue(state,input) {
+  if(state.paused)return null;
+  const role=input.hook_event_name==='UserPromptSubmit'?'user':input.hook_event_name==='Stop'?'assistant':null;
+  if(!role||!identifier(input.session_id))fail('Unsupported capture hook or session identifier.');
+  const content=role==='user'?input.prompt:input.last_assistant_message;
+  if(typeof content!=='string'||!content.trim())return null;
+  if(Buffer.byteLength(content)>MAX_CONTENT)fail('This message exceeds the 64 KiB capture limit; it was not truncated or uploaded.');
+  if(Buffer.byteLength(JSON.stringify(content))>230*1024)fail('This message exceeds the encoded capture request limit; it was not truncated or uploaded.');
+  let session=state.sessions.find(value=>value.id===input.session_id);
+  if(!session) {
+    if(role==='assistant')return null; // Never attach an orphan Stop to a guessed turn.
+    if(state.sessions.length>=MAX_SESSIONS)fail('This capture scope reached 100 sessions. Preserve its state before starting another.');
+    session={id:input.session_id,remote_id:'occap_'+hash(state.scope.project+'\0'+input.session_id),events:[],turns:[],next:0};state.sessions.push(session);
+  }
+  if(permanent(session.issue))return session;
+  let turn;
+  if(state.scope.provider==='codex') {
+    if(!identifier(input.turn_id))fail('This Codex version did not provide a turn ID. Capture skipped; update the client and inspect /hooks.');
+    turn=session.turns.find(value=>value.id===input.turn_id);
+    if(!turn) {if(role==='assistant')return null;turn={id:input.turn_id,token:hash(input.turn_id)};session.turns.push(turn);}
+  } else if(role==='user') {
+    // prompt_id is optional in Claude versions. Without it, an unfinished
+    // identical prompt is treated as a hook replay; completed turns are new.
+    const last=session.turns.at(-1), native=identifier(input.prompt_id)?input.prompt_id:null;
+    if(native)turn=session.turns.find(value=>value.id===native);
+    else if(last&&!last.closed&&last.user_hash===hash(content))turn=last;
+    if(!turn){turn={id:native||crypto.randomUUID(),token:crypto.randomUUID(),user_hash:hash(content)};session.turns.push(turn);}
+  } else turn=session.turns.at(-1);
+  if(!turn)return null;
+  const id=hash(turn.token+'\0'+role),prior=session.events.find(value=>value.id===id);
+  if(prior) {
+    if(prior.hash!==hash(content)){session.issue='event_conflict';return session;}
+    return session;
+  }
+  if(state.sessions.reduce((count,item)=>count+item.events.length,0)>=MAX_EVENTS)fail('This capture scope reached 20,000 events. No queued event was discarded.');
+  session.events.push({id,sequence:session.next++,role,content,hash:hash(content),state:'queued',attempts:0,next_attempt_at:0});
+  if(role==='assistant')turn.closed=true;
+  return session;
+}
+async function flushOne(client,scope,sessionId,{explicit=false,timeout=1200}={}) {
+  const batch=await storage(scope,async(state,save)=>{
+    const session=state.sessions.find(value=>value.id===sessionId);
+    if(!session||state.paused||permanent(session.issue))return null;
+    let events=[];
+    for(const event of session.events.filter(event=>event.state==='queued')) {
+      if(!explicit&&(event.attempts>=3||event.next_attempt_at>Date.now()))break;
+      const next=[...events,{id:event.id,sequence:event.sequence,role:event.role,content:event.content}];
+      if(next.length>100||Buffer.byteLength(JSON.stringify({provider:scope.provider,session_id:session.remote_id,events:next}))>240*1024)break;
+      events=next;
+    }
+    if(!events.length)return null;
+    for(const item of events){const event=session.events.find(value=>value.id===item.id);event.attempts++;event.next_attempt_at=Date.now()+Math.min(60000,1000*2**Math.min(event.attempts,6));}
+    await save();
+    return {provider:scope.provider,session_id:session.remote_id,events};
+  });
+  if(!batch)return;
+  let receipt,issue;
+  try {receipt=validateCaptureReceipt(await client.request('/api/v1/sessions/events',{method:'POST',body:batch,timeout,maxResponseBytes:64*1024}),batch.events.length);}
+  catch(error){issue=safeIssue(error);}
+  await storage(scope,async(state,save)=>{
+    const session=state.sessions.find(value=>value.id===sessionId);
+    if(!session)return;
+    const events=batch.events.map(item=>session.events.find(value=>value.id===item.id&&value.sequence===item.sequence&&value.role===item.role&&value.hash===hash(item.content)));
+    if(events.some(event=>!event))fail('The queued capture changed while its request was in flight. Preserve the spool.');
+    if(receipt) {
+      if(!session.receipt||session.receipt.event_count<=receipt.event_count)session.receipt=receipt;
+      if(!permanent(session.issue))delete session.issue;
+      delete session.status_issue;session.status_verified_at=receipt.observed_at;
+      for(const event of events){event.state='acknowledged';delete event.content;}
+    } else if(events.some(event=>event.state==='queued')&&!permanent(session.issue))session.issue=issue;
+    await save();
+  });
+}
+
+function summary(state) {
+  return {configured:true,paused:state.paused,provider:state.scope.provider,project:state.scope.project,server:state.scope.server,
+    sessions:state.sessions.map(session=>({session_id:session.id,state:permanent(session.issue)?'blocked':session.events.some(event=>event.state==='queued')?'queued':session.status_issue?'verification_unavailable':session.receipt?'lexical_ready':'configured',queued_events:session.events.filter(event=>event.state==='queued').length,acknowledged_events:session.events.filter(event=>event.state==='acknowledged').length,issue:session.issue||null,current_verification:session.status_issue?{state:'unavailable',issue:session.status_issue}:session.status_verified_at?{state:'verified',observed_at:session.status_verified_at}:{state:'not_checked'},...(session.receipt?{last_acknowledgement:session.receipt}:{})}))};
+}
+export async function captureHook(input,options,client) {
+  const scope=await assertCaptureHook(input,options,client);
+  const sessionId=await storage(scope,async(state,save)=>{
+    const session=enqueue(state,input);await save();return session?.id;
+  });
+  if(sessionId) {
+    try {await verifyAgentIdentity(client,1200);await flushOne(client,scope,sessionId,{timeout:1200});}
+    catch(error){await storage(scope,async(state,save)=>{const session=state.sessions.find(value=>value.id===sessionId);if(session&&!permanent(session.issue)){session.issue=safeIssue(error);await save();}});}
+  }
+  return storage(scope,async state=>summary(state));
+}
+export async function assertCaptureHook(input,options,client) {
+  const scope=await projectScope(client,options.provider,options.project);
+  // Both the host's event cwd and executing hook must belong to this exact
+  // installed project. Never infer scope from transcript paths or file contents.
+  if(typeof input?.cwd!=='string'||await fs.realpath(input.cwd)!==scope.project||await fs.realpath(process.cwd())!==scope.project)fail('Hook project does not match the installed capture scope.');
+  await storage(scope,async()=>{}); // Require the explicit installed capture registration.
+  return scope;
+}
+export async function captureCommand(rest,options,client,{stdout=text=>process.stdout.write(text)}={}) {
+  const [command,...extra]=rest;
+  if(extra.length||!['status','flush','pause','resume'].includes(command))fail('Choose capture status, flush, pause, or resume.');
+  allowedOptions(options,['provider','project','timeout',...AGENT_OPTIONS],'capture');
+  if(options.timeout!==undefined&&command!=='flush')fail('--timeout is only supported by capture flush.');
+  const timeout=decimal(options.timeout,'timeout',1,60,10),scope=await projectScope(client,options.provider,options.project),deadline=Date.now()+timeout*1000;
+  if(command==='pause'||command==='resume') {
+    await storage(scope,async(state,save)=>{state.paused=command==='pause';await save();});
+  } else {
+    const snapshot=await storage(scope,async state=>({paused:state.paused,sessions:state.sessions.map(session=>({id:session.id,remote_id:session.remote_id,pending:session.events.some(event=>event.state==='queued'),blocked:permanent(session.issue)}))}));
+    try {await verifyAgentIdentity(client,Math.min(2000,timeout*1000));}
+    catch(error){
+      await storage(scope,async(state,save)=>{for(const session of state.sessions)session.status_issue=safeIssue(error);await save();});
+      if(command==='flush')throw error;
+      const value=await storage(scope,async state=>summary(state));
+      stdout(options.json?JSON.stringify(value,null,2)+'\n':'Current capture verification is unavailable. Previous acknowledgements are historical; check account access.\n');return 1;
+    }
+    if(command==='flush') {
+      if(snapshot.paused)fail('Capture is paused. Resume explicitly before flushing queued messages.');
+      let operations=0;
+      for(const session of snapshot.sessions) {
+        if(Date.now()>=deadline||operations>=10)break;
+        if(session.pending&&!session.blocked){await flushOne(client,scope,session.id,{explicit:true,timeout:Math.max(1,Math.min(2000,deadline-Date.now()))});operations++;}
+      }
+    } else {
+      // Only query known captured sessions, with a shared finite deadline.
+      for(const session of snapshot.sessions.slice(-20)) {
+        if(Date.now()>=deadline)break;
+        let receipt,issue;
+        try {receipt=validateCaptureReceipt(await client.request('/api/v1/sessions/events/status?'+new URLSearchParams({provider:scope.provider,session_id:session.remote_id}),{timeout:Math.max(1,Math.min(1500,deadline-Date.now())),maxResponseBytes:64*1024}));}
+        catch(error){issue=error.status===410?'session_deleted':error.status===404?'not_received':safeIssue(error);}
+        await storage(scope,async(state,save)=>{const current=state.sessions.find(value=>value.id===session.id);if(current){if(receipt){if(!current.receipt||current.receipt.event_count<=receipt.event_count)current.receipt=receipt;current.status_verified_at=receipt.observed_at;delete current.status_issue;}else{current.status_issue=issue;if(issue==='session_deleted')current.issue=issue;}await save();}});
+      }
+    }
+  }
+  const result=await storage(scope,async state=>summary(state));
+  stdout(options.json?JSON.stringify(result,null,2)+'\n':`Capture ${result.paused?'paused':'configured'}: ${displayLine(result.provider)} in ${displayLine(result.project)}\n`+result.sessions.map(session=>`${displayLine(session.session_id)}: ${session.state}; ${session.queued_events} queued, ${session.acknowledged_events} acknowledged${session.issue?' ('+session.issue+')':''}${session.current_verification.issue?' (current verification: '+session.current_verification.issue+')':''}\n`).join(''));
+  return result.sessions.some(session=>session.state==='blocked'||session.current_verification.state==='unavailable'||command==='flush'&&session.queued_events)?1:0;
+}

package/src/client.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+export const configDir = () => process.env.OPENCRAWL_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencrawl');
+export async function readConfig() {
+  try {
+    const value = JSON.parse(await fs.readFile(path.join(configDir(), 'config.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid configuration');
+    if (value.version !== undefined && value.version !== 2) throw new Error('Unsupported configuration version');
+    return value;
+  }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw new Error('OpenCrawl config is invalid. Repair config.json or choose a separate --config-dir before signing in.'); }
+}
+export async function writeConfig(value) {
+  const dir = configDir();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, 'config.json');
+  const temp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  await fs.rename(temp, file);
+  await fs.chmod(file, 0o600);
+}
+export function validateBaseUrl(input) {
+  if (typeof input !== 'string' || !/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#\\]+\/?$/.test(input.trim()))
+    throw new Error('Server must be an origin without credentials, a path, query parameters, or a fragment.');
+  let url;
+  try { url = new URL(input); } catch { throw new Error('Server must be a valid HTTP or HTTPS URL.'); }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Server must be an origin without credentials, a path, query parameters, or a fragment.');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Use HTTPS, or HTTP on localhost.');
+  }
+  return url.origin;
+}
+
+const profileId = (server, user, workspace) => 'p_' + crypto.createHash('sha256').update(`${server}\0${user}\0${workspace}`).digest('hex').slice(0, 24);
+function validToken(token) {
+  if (typeof token !== 'string' || !token.trim() || token.length > 8192 || /\s/.test(token.trim())) throw new Error('The explicitly selected API key is empty or invalid. Sign in again.');
+  return token.trim();
+}
+function selectedProfile(config, id) {
+  if (!id) return null;
+  if (config.version !== 2 || typeof id !== 'string' || !/^p_[a-f0-9]{24}$/.test(id) || !Object.hasOwn(config.profiles || {}, id))
+    throw new Error('Saved account profile not found. Run opencrawl profiles or sign in again.');
+  const value = config.profiles[id];
+  if (!value || typeof value !== 'object') throw new Error('Saved account profile is invalid. Sign in again.');
+  const server = validateBaseUrl(value.server);
+  if (value.origin !== server || !/^usr_[a-f0-9]{32}$/.test(value.userId || '') || !/^ws_[a-f0-9]{32}$/.test(value.workspaceId || '') || id !== profileId(server, value.userId, value.workspaceId))
+    throw new Error('Saved credential binding is invalid. Sign in again.');
+  return { ...value, server, id };
+}
+
+/** Pure selection: a saved credential never follows a changed destination. */
+export function resolveCredentials(config, overrides = {}, environment = process.env) {
+  const pinned = overrides.account !== undefined;
+  const profile = pinned ? selectedProfile(config, overrides.account) : config.version === 2 ? selectedProfile(config, config.activeProfile) : null;
+  const baseUrl = validateBaseUrl(overrides.server ?? (pinned ? profile.server : environment.OPENCRAWL_URL ?? config.server ?? profile?.server ?? 'http://localhost:8000'));
+  if (pinned && baseUrl !== profile.server) throw new Error('The selected account is bound to another server. Choose that server’s account or sign in there first.');
+  // An explicit programmatic token is an intentional destination choice. A
+  // pinned account uses its own credential rather than ambient shell defaults.
+  const explicit = overrides.token !== undefined ? overrides.token : !pinned && environment.OPENCRAWL_API_KEY !== undefined ? environment.OPENCRAWL_API_KEY : undefined;
+  if (explicit !== undefined) return { baseUrl, token: validToken(explicit), credentialSource: 'explicit', profile: null };
+  if (profile?.apiKey && profile.origin === baseUrl) return { baseUrl, token: validToken(profile.apiKey), credentialSource: 'profile', profile };
+  const credentialError = config.apiKey ? 'This saved key predates server binding. Run opencrawl login with an explicitly supplied key before using it.'
+    : profile?.apiKey ? 'The saved key belongs to another server. Sign in to this server explicitly; no saved key was sent.'
+    : pinned ? 'This account has no saved key. Sign in to the same server and workspace again, or choose another account.'
+    : 'Sign in with opencrawl login, or explicitly set OPENCRAWL_API_KEY for the intended server.';
+  return { baseUrl, token: null, credentialSource: 'none', profile, credentialError };
+}
+
+export function loggedInConfig(config, server, apiKey, identity) {
+  server = validateBaseUrl(server);
+  if (!/^usr_[a-f0-9]{32}$/.test(identity?.user?.id || '') || !/^ws_[a-f0-9]{32}$/.test(identity?.workspace?.id || ''))
+    throw new Error('The server did not return a valid workspace identity. No credential was saved.');
+  const id = profileId(server, identity.user.id, identity.workspace.id);
+  const next = { ...config, version: 2, server, activeProfile: id, profiles: { ...(config.version === 2 ? config.profiles : {}),
+    [id]: { server, origin: server, userId: identity.user.id, workspaceId: identity.workspace.id,
+      userName: String(identity.user.name || '').slice(0, 100), workspaceName: String(identity.workspace.name || '').slice(0, 100), apiKey: validToken(apiKey) } } };
+  delete next.apiKey;
+  return next;
+}
+
+export function profileSummaries(config) {
+  return Object.keys(config.version === 2 ? config.profiles || {} : {}).map(id => {
+    const profile = selectedProfile(config, id);
+    return { id, server: profile.server, user: profile.userName, workspace: profile.workspaceName,
+      user_id: profile.userId, workspace_id: profile.workspaceId, configured: !!profile.apiKey, active: id === config.activeProfile };
+  });
+}
+
+export function loggedOutConfig(config, account) {
+  const next = { ...config, profiles: { ...(config.profiles || {}) } };
+  const profile = account !== undefined ? selectedProfile(config, account) : config.version === 2 ? selectedProfile(config, config.activeProfile) : null;
+  if (profile) { next.profiles[profile.id] = { ...config.profiles[profile.id] }; delete next.profiles[profile.id].apiKey; }
+  delete next.apiKey;
+  return next;
+}
+
+export async function createClient(overrides = {}) {
+  const config = await readConfig();
+  const { baseUrl, token, profile, credentialSource, credentialError } = resolveCredentials(config, overrides);
+  const publicProfile = profile ? Object.fromEntries(['id', 'server', 'userId', 'workspaceId', 'userName', 'workspaceName'].map(key => [key, profile[key]])) : null;
+  return { baseUrl, configured: Boolean(token), profile: publicProfile, credentialSource, credentialError, identity: token ? crypto.createHash('sha256').update(token).digest('hex').slice(0, 16) : 'anonymous', async request(route, { method = 'GET', body, authenticated = true, timeout = 30000, protocolVersion, channel, maxResponseBytes, signal, idempotencyKey, responseType } = {}) {
+    // The exported client must not let a caller turn an origin into URL userinfo
+    // or replace its port/host by supplying something other than a path.
+    if (typeof route !== 'string' || !/^\/(?!\/)/.test(route) || /[\\\u0000-\u0020\u007f]/.test(route))
+      throw new Error('Request routes must be absolute paths on the selected server.');
+    let destination;
+    try { destination = new URL(route, baseUrl); } catch { throw new Error('Request route is invalid.'); }
+    if (destination.origin !== baseUrl || destination.username || destination.password)
+      throw new Error('Request routes cannot change the selected server.');
+    if (authenticated && !token) throw new Error(credentialError);
+    if(responseType!==undefined&&responseType!=='png')throw new Error('Unsupported response type.');
+    const headers = { Accept: responseType==='png'?'image/png':route === '/mcp' ? 'application/json, text/event-stream' : 'application/json', 'X-OpenCrawl-Client': channel || (route === '/mcp' ? 'mcp' : 'cli') };
+    if (protocolVersion) headers['MCP-Protocol-Version'] = protocolVersion;
+    if (idempotencyKey !== undefined) {
+      if (!(method === 'POST' || method === 'GET' && destination.pathname === '/api/research/agents/receipts/by-key') || typeof idempotencyKey !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(idempotencyKey)) throw new Error('Invalid idempotency key for this request.');
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+    if (authenticated) headers.Authorization = `Bearer ${token}`;
+    const multipart = typeof FormData !== 'undefined' && body instanceof FormData;
+    if (body !== undefined && !multipart) headers['Content-Type'] = 'application/json';
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException('Timed out', 'TimeoutError')), timeout);
+    timer.unref?.();
+    try {
+    let response;
+    try {
+      response = await fetch(destination.href, { method, headers, body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
+        signal: controller.signal, redirect: 'error' });
+    } catch (error) { throw new Error(error.name === 'TimeoutError' ? 'OpenCrawl request timed out.' : 'Cannot reach OpenCrawl. Check your server URL and connection.'); }
+    if(responseType==='png'&&response.ok){
+      const cap=2*1024*1024;if(response.headers.get('content-type')?.split(';')[0]?.trim()!=='image/png'||Number(response.headers.get('content-length'))>cap){await response.body?.cancel();throw new Error('Invalid bounded PNG response.');}
+      const reader=response.body?.getReader();if(!reader)throw new Error('Missing PNG response.');const bytes=Buffer.alloc(cap);let length=0;const cancel=()=>{void reader.cancel().catch(()=>{});};if(controller.signal.aborted)cancel();else controller.signal.addEventListener('abort',cancel,{once:true});
+      try{while(true){const part=await reader.read();if(part.done)break;if(length+part.value.byteLength>cap){await reader.cancel();throw new Error('PNG response exceeds its limit.');}bytes.set(part.value,length);length+=part.value.byteLength;}}finally{controller.signal.removeEventListener('abort',cancel);reader.releaseLock();}
+      if(controller.signal.aborted)throw new Error('PNG request cancelled.');
+      if(length<33||!bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10]))||bytes.subarray(12,16).toString()!=='IHDR'||bytes.readUInt32BE(16)<320||bytes.readUInt32BE(16)>1920||bytes.readUInt32BE(20)<240||bytes.readUInt32BE(20)>1080)throw new Error('Invalid PNG signature.');return bytes.subarray(0,length);
+    }
+    let text;
+    if (maxResponseBytes !== undefined) {
+      if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > 4 * 1024 * 1024) throw new Error('Invalid response byte limit.');
+      const reader=response.body?.getReader();const bytes=Buffer.alloc(maxResponseBytes);let length=0;
+      if (reader) {
+        try {
+          while (true) { const part=await reader.read();if (part.done) break;length+=part.value.byteLength;
+            if (length>maxResponseBytes) { await reader.cancel();throw new Error('OpenCrawl response exceeds the allowed byte limit.'); }
+            bytes.set(part.value,length-part.value.byteLength);
+          }
+        } finally { reader.releaseLock(); }
+      }
+      text=bytes.subarray(0,length).toString('utf8');
+    } else text = await response.text();
+    let value;
+    try { value = text ? JSON.parse(text) : null; } catch { throw new Error(`Server returned an unexpected response (${response.status}).`); }
+    if (!response.ok) {
+      const detail = typeof value?.detail === 'string' ? value.detail : typeof value?.error === 'string' ? value.error : response.statusText;
+      const error=new Error(`OpenCrawl ${response.status}: ${detail}`);error.status=response.status;
+      if (typeof value?.code === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(value.code)) error.code=value.code;
+      throw error;
+    }
+    return value;
+    } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  }};
+}
+export async function search(query, options = {}) {
+  const client = await createClient(options);
+  return client.request('/api/v1/search', { method: 'POST', body: { query, limit: options.limit || 8, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}) } });
+}
+export async function context(query, options = {}) {
+  const client = await createClient(options);
+  return client.request('/api/v1/context', { method: 'POST', body: { query, limit: options.limit || 8, budget: options.budget || 2000, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}) } });
+}