@bitefoundry/retrieviewer 0.0.12 → 0.0.14

package/retrieviewer-attention.d.mts

@@ -0,0 +1,33 @@
+export interface AttentionSnapshot {
+ source: string;
+ scope: string;
+ items: {id: string; generation: string; turnId: number | null; requestId?: string; kind: 'approval' | 'input'}[];
+}
+export interface AttentionStatus {
+ state: 'connecting' | 'connected' | 'unavailable' | 'paused' | 'stale' | 'off';
+ pendingCount: number;
+ retainedNotices: number;
+ inFlight: boolean;
+ judging?: boolean;
+ lastJudgment?: 'model_notify' | 'rule_override' | 'rule_fallback' | null;
+}
+export function validateAttentionSnapshot(value: unknown): AttentionSnapshot;
+/** Host owns tick/lifetime. Import and construction start no timers or I/O. */
+export function createAttentionMonitor(options: {
+ readSnapshot: (options: {signal: AbortSignal}) => Promise<AttentionSnapshot>;
+ onNotice: (notice: {kind: 'approval' | 'input'; side: 'left'}) => boolean;
+ onClear?: () => void;
+ onChange?: (status: AttentionStatus) => void;
+ /** Anonymous metadata only. Confirmed pending alerts cannot be suppressed. */
+ judgeNotice?: (input: {kind: 'approval' | 'input'; pendingCount: number; signal: AbortSignal}) => Promise<{decision: 'notify' | 'ignore' | 'uncertain'}>;
+ judgeTimeoutMs?: number;
+ now?: () => number;
+ intervalMs?: number;
+ staleMs?: number;
+ noticeCooldownMs?: number;
+}): {
+ tick(options?: {active?: boolean}): void;
+ readonly status: AttentionStatus;
+ settled(): Promise<void>;
+ dispose(): void;
+};

package/retrieviewer-attention.mjs

@@ -0,0 +1,99 @@
+// Opt-in attention coordinator. No I/O, timers, models or pet assets on import.
+// Screen/app text is data, never an instruction or an executable action.
+const MAX_ITEMS=32,MAX_SEEN=128;
+const bounded=(value,max=128)=>typeof value==='string'&&value.length>0&&value.length<=max&&!/[\x00-\x1f\x7f]/.test(value);
+export function validateAttentionSnapshot(value){
+ if(!value||!bounded(value.source,32)||!bounded(value.scope,256)||!Array.isArray(value.items)||value.items.length>MAX_ITEMS)throw Error('Invalid attention snapshot');
+ const identities=new Set();
+ const items=value.items.map(item=>{
+  if(!item||!bounded(item.id)||!bounded(item.generation)||!(item.turnId===null||Number.isSafeInteger(item.turnId)&&item.turnId>=1)||item.requestId!==undefined&&!bounded(item.requestId)||item.turnId===null&&item.requestId===undefined||!['approval','input'].includes(item.kind))throw Error('Invalid attention item');
+  const key=JSON.stringify([item.id,item.generation,item.turnId,item.requestId??null]);if(identities.has(key))throw Error('Duplicate attention item');identities.add(key);
+  // Do not retain arbitrary source fields, output text, prompts, paths or tokens.
+  return {id:item.id,generation:item.generation,turnId:item.turnId,...item.requestId===undefined?{}:{requestId:item.requestId},kind:item.kind};
+ });
+ return {source:value.source,scope:value.scope,items};
+}
+
+export function createAttentionMonitor({readSnapshot,onNotice,onClear=()=>{},onChange=()=>{},judgeNotice,judgeTimeoutMs=3500,now=()=>performance.now(),intervalMs=5000,staleMs=15000,noticeCooldownMs=20000}={}){
+ if(typeof readSnapshot!=='function'||typeof onNotice!=='function'||typeof onClear!=='function'||typeof onChange!=='function'||typeof now!=='function')throw TypeError('Attention callbacks must be functions');
+ if(judgeNotice!==undefined&&typeof judgeNotice!=='function')throw TypeError('judgeNotice must be a function');
+ if(!Number.isFinite(judgeTimeoutMs)||judgeTimeoutMs<100||judgeTimeoutMs>15000)throw RangeError('Invalid judge timeout');
+ if(!Number.isFinite(intervalMs)||intervalMs<1000||intervalMs>60000||!Number.isFinite(staleMs)||staleMs<intervalMs*2||staleMs>300000||!Number.isFinite(noticeCooldownMs)||noticeCooldownMs<1000||noticeCooldownMs>300000)throw RangeError('Invalid attention timing');
+ let disposed=false,paused=false,flight=null,nextRead=0,nextNotice=0,lastSuccess=null,snapshot=null,state='connecting',lastReport='',cueKey=null,judgment=null,lastJudgment=null;
+ const seen=new Map();
+ const identity=(value,item)=>JSON.stringify([value.source,value.scope,item.id,item.generation,item.turnId,item.requestId??null]);
+ const clearCue=()=>{if(cueKey!==null){cueKey=null;onClear();}};
+ const cancelJudgment=()=>{const old=judgment;judgment=null;old?.controller.abort();};
+ const report=()=>({state,pendingCount:snapshot?.items.length??0,retainedNotices:seen.size,inFlight:flight!==null,...judgeNotice?{judging:!!judgment&&!judgment.ready,lastJudgment}:{}});
+ const changed=()=>{const key=state+'|'+(snapshot?.items.length??0);if(key!==lastReport){lastReport=key;onChange(report());}};
+ const clear=next=>{snapshot=null;lastSuccess=null;state=next;cancelJudgment();clearCue();changed();};
+ function startRead(t){
+  const operation={controller:new AbortController()};flight=operation;nextRead=t+intervalMs;
+  operation.done=(async()=>{
+   try{
+    const result=validateAttentionSnapshot(await readSnapshot({signal:operation.controller.signal}));
+    if(disposed||paused||flight!==operation)return;
+    // A scope change cannot inherit either pending facts or dedupe identities.
+    if(snapshot&&(snapshot.scope!==result.scope||snapshot.source!==result.source))seen.clear();
+    snapshot=result;lastSuccess=now();state='connected';
+    if(cueKey!==null&&!snapshot.items.some(item=>identity(snapshot,item)===cueKey))clearCue();
+    if(judgment&&!snapshot.items.some(item=>identity(snapshot,item)===judgment.key))cancelJudgment();
+   }catch{
+    if(disposed||paused||flight!==operation)return;
+    // No source stderr, credentials, or stale pending facts escape on failure.
+    clear('unavailable');
+   }finally{
+    if(flight===operation){flight=null;nextRead=now()+intervalMs;if(!disposed&&!paused)changed();}
+   }
+  })();
+ }
+ return {
+  tick({active=true}={}){
+   if(disposed)return;
+   const t=now();if(!Number.isFinite(t))throw RangeError('Invalid attention clock');
+   if(!active){
+    if(!paused){paused=true;const old=flight;flight=null;old?.controller.abort();clear('paused');}
+    return;
+   }
+   if(paused){paused=false;nextRead=t;state='connecting';changed();}
+   if(snapshot&&t-lastSuccess>=staleMs)clear('stale');
+   if(!flight&&t>=nextRead)startRead(t);
+   // A refresh already in flight may resolve/replace the candidate. Do not emit
+   // an old cue in the microtask gap just before that fresh snapshot arrives.
+   if(!flight&&snapshot&&state==='connected'&&t<lastSuccess+staleMs&&t>=nextNotice){
+    // Approval and generic input for the same exact turn are one notification.
+    let item=null;
+    for(const row of snapshot.items)if(!seen.has(identity(snapshot,row))){if(!item)item=row;if(row.kind==='approval'){item=row;break;}}
+    if(item&&judgeNotice){
+     const key=identity(snapshot,item);
+     if(judgment?.key!==key){
+      cancelJudgment();const operation={key,controller:new AbortController(),ready:false,start:t};judgment=operation;
+      const facts={kind:item.kind,pendingCount:snapshot.items.length,signal:operation.controller.signal};
+      // Only anonymous enums/counts leave the coordinator; identities stay local.
+      operation.done=Promise.resolve().then(()=>{if(operation.controller.signal.aborted)throw Error('Canceled judgment');return judgeNotice(facts);}).then(result=>{
+       if(judgment===operation&&!disposed&&!paused&&!operation.controller.signal.aborted){operation.decision=['notify','ignore','uncertain'].includes(result?.decision)?result.decision:'uncertain';operation.ready=true;}
+      },()=>{if(judgment===operation&&!disposed&&!paused){operation.decision='uncertain';operation.ready=true;}});
+     }
+     if(!judgment.ready&&t-judgment.start>=judgeTimeoutMs){judgment.ready=true;judgment.decision='uncertain';judgment.controller.abort();}
+     if(!judgment.ready){changed();return;}
+     // These are confirmed pending human-input facts, not speculative screen
+     // guesses. A model may advise, but may never hide them or authorize input.
+    }
+    if(item&&onNotice({kind:item.kind,side:'left'})===true){
+     if(judgment)lastJudgment=judgment.decision==='notify'?'model_notify':judgment.decision==='ignore'?'rule_override':'rule_fallback';
+     const key=identity(snapshot,item);seen.set(key,true);cueKey=key;
+     // Still-pending identities cannot be evicted into repeated notifications.
+     const live=new Set(snapshot.items.map(row=>identity(snapshot,row)));
+     for(const prior of seen.keys()){if(seen.size<=MAX_SEEN)break;if(!live.has(prior))seen.delete(prior);}
+     nextNotice=t+noticeCooldownMs;
+     cancelJudgment();
+    }
+   }
+   changed();
+  },
+  get status(){return report();},
+  // For host shutdown/verification, not a second polling loop.
+  async settled(){await flight?.done;await judgment?.done;},
+  dispose(){if(disposed)return;disposed=true;const old=flight;flight=null;old?.controller.abort();cancelJudgment();clearCue();snapshot=null;seen.clear();state='off';},
+ };
+}

package/retrieviewer-cli.mjs

@@ -13,7 +13,9 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
-  retrieviewer desktop [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot]
+  retrieviewer desktop [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot] [--watch stackbite|off] [--brain openrouter|off]
+  retrieviewer brain-check [--json]
+  retrieviewer attention [--json]
   retrieviewer desktop-status [--json]
   retrieviewer desktop-stop
   retrieviewer desktop-clean --yes
@@ -28,12 +30,19 @@ use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is ad
 Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
 app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 Return style defaults to auto (mix all three). Restart the companion to change it.
+Watch is OFF by default. Inside a live StackBite Seat, --watch stackbite reads only
+that Room's pending-input metadata. No screen capture, clicks or approvals.
+Hidden/paused companions stop polling. attention performs one read-only check.
+Brain is OFF by default. --brain openrouter requires --watch stackbite and
+OPENROUTER_API_KEY; sends only anonymous event kinds/counts to paid DeepSeek V4.1
+Flash 1017 with token price ceilings. Failures fall back to rule alerts.
+brain-check sends one synthetic event and incurs API usage charges.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
  for(let i=0;i<rest.length;i++){
   const token=rest[i];
-  if(token==='--agent'||token==='--ink'||token==='--return-style'){
+  if(token==='--agent'||token==='--ink'||token==='--return-style'||token==='--watch'||token==='--brain'){
    const key=token.slice(2);
    if(options[key]||!rest[i+1]||rest[i+1].startsWith('-'))throw Error(token+' requires one value');
    options[key]=rest[++i];
@@ -43,19 +52,37 @@ export function parseArguments(args){
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
  if(options.ink&&!['cream','gold','dark'].includes(options.ink))throw Error('--ink must be cream, gold or dark');
  if(options['return-style']&&!['auto','brake','trot','run-trot'].includes(options['return-style']))throw Error('--return-style must be auto, brake, trot or run-trot');
- if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
- const allowed={desktop:['ink','return-style'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
+ if(options.watch&&!['off','stackbite'].includes(options.watch))throw Error('--watch must be stackbite or off');
+ if(options.brain&&!['off','openrouter'].includes(options.brain))throw Error('--brain must be openrouter or off');
+ if(options.brain==='openrouter'&&options.watch!=='stackbite')throw Error('--brain openrouter requires --watch stackbite');
+ if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','attention','brain-check','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
+ const allowed={desktop:['ink','return-style','watch','brain'],attention:['json'],'brain-check':['json'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
 export async function runCli(args,{input=process.stdin,output=process.stdout,error=process.stderr,installer=createInstaller(),desktop}={}){
  const {command,options}=parseArguments(args),emit=value=>output.write(JSON.stringify(value,null,2)+'\n');
  if(['help','--help','-h'].includes(command)){output.write(HELP);return 0;}
+ if(command==='brain-check'){
+  const {createOpenRouterBrain,BrainError}=await import('./integrations/openrouter/brain.mjs');
+  const brain=createOpenRouterBrain({timeoutMs:8000});
+  try{const result=await brain.decide({kind:'approval',pendingCount:1});emit({ok:true,synthetic:true,...result,brain:brain.status});return 0;}
+  catch(error){emit({ok:false,synthetic:true,error:error instanceof BrainError?error.code:'unavailable',brain:brain.status});return 2;}
+  finally{brain.dispose();}
+ }
+ if(command==='attention'){
+  const {createStackBiteSource}=await import('./integrations/stackbite/attention.mjs');
+  const snapshot=await createStackBiteSource().readSnapshot();
+  // Diagnostic metadata only; prompts/output/credentials were discarded upstream.
+  if(options.json)emit({...snapshot,pendingCount:snapshot.items.length});
+  else output.write(`StackBite current Room: ${snapshot.items.length} pending input item(s). No screen capture or actions.\n`);
+  return 0;
+ }
  if(command.startsWith('desktop')){
   if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
   const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
   const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
-  emit(await api[action]({...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{} }));return 0;
+  emit(await api[action]({...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{},...options.watch?{watch:options.watch}:{},...options.brain?{brain:options.brain}:{} }));return 0;
  }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){

package/retrieviewer-config.mjs

@@ -1,5 +1,5 @@
 // Tiny runtime settings API. No art, processes, timers or I/O on import.
-import {homedir} from 'node:os';
+import {homedir,hostname} from 'node:os';
 import {join,resolve} from 'node:path';
 import {readFile,mkdir,lstat,open,rename,unlink} from 'node:fs/promises';
 import {randomUUID} from 'node:crypto';
@@ -30,8 +30,19 @@ export async function writeAtomicJson(path,value){
 export async function withSettingsLock(fn,options={}){
  const paths=getConfigPaths(options);await noLink(paths.root);await mkdir(paths.root,{recursive:true,mode:0o700});
  await noLink(paths.lock);let handle;
- try{handle=await open(paths.lock,'wx',0o600);}catch(e){if(e.code==='EEXIST')throw Error('Retrieviewer settings are locked by another operation; retry when it finishes.');throw e;}
- try{return await fn(paths);}finally{await handle.close();await unlink(paths.lock);}
+ const owner={owner:'retrieviewer-settings-lock-v1',pid:process.pid,host:hostname(),startedAt:new Date().toISOString(),token:randomUUID()};
+ try{handle=await open(paths.lock,'wx',0o600);}catch(e){
+  if(e.code!=='EEXIST')throw e;
+  let pid;try{await noLink(paths.lock);const info=JSON.parse(await readFile(paths.lock,'utf8'));if(info.owner===owner.owner&&Number.isSafeInteger(info.pid)&&info.pid>0)pid=info.pid;}catch{}
+  throw Error(`Retrieviewer settings are locked${pid?' (owner PID '+pid+')':''}: ${paths.lock}. Retry when it finishes. If the owner crashed, stop ALL Retrieviewer settings writers first, then follow INSTALLING.md#recovering-an-interrupted-settings-change. No lock was removed automatically.`);
+ }
+ try{await handle.writeFile(JSON.stringify(owner)+'\n');await handle.sync();return await fn(paths);}
+ finally{
+  try{await handle.close();}finally{
+   // Do not remove a replacement lock if someone moved ours during the operation.
+   try{await noLink(paths.lock);const current=JSON.parse(await readFile(paths.lock,'utf8'));if(current.token===owner.token)await unlink(paths.lock);}catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+ }
 }
 export async function setAgentEnabled(agent,enabled,options={}){
  agentId(agent);if(typeof enabled!=='boolean')throw TypeError('enabled must be boolean');

package/retrieviewer-plugin.d.mts

@@ -21,7 +21,7 @@ export interface PetPluginScheduler {
 export interface PetPluginOptions {
   host: PetPluginHost;
   petOptions?: PetOptions;
-  /** Scheduled frame rate, default 30. */
+  /** Scheduled frame rate, default 30; 1000/2147483647 through 120 inclusive. */
   fps?: number;
   /** Default: performance.now() with setTimeout/clearTimeout, used only after start(). */
   scheduler?: PetPluginScheduler;

package/retrieviewer-plugin.mjs

@@ -11,7 +11,7 @@ export async function createPetPlugin({host,petOptions,fps=30,scheduler}={}){
  fn(host.getSize,'host.getSize');fn(host.render,'host.render');
  if(host.clear!==undefined)fn(host.clear,'host.clear');
  if(host.onError!==undefined)fn(host.onError,'host.onError');
- if(typeof fps!=='number'||!Number.isFinite(fps)||fps<=0||fps>120)throw RangeError('fps must be within (0, 120]');
+ if(typeof fps!=='number'||!Number.isFinite(fps)||fps<=0||fps>120||1000/fps>2147483647)throw RangeError('fps must be within [1000/2147483647, 120] (bounded timer delay)');
  if(scheduler!==undefined){
   if(!scheduler||typeof scheduler!=='object')throw TypeError('scheduler must be an object');
   fn(scheduler.now,'scheduler.now');fn(scheduler.schedule,'scheduler.schedule');fn(scheduler.cancel,'scheduler.cancel');

package/retrieviewer.d.mts

@@ -40,6 +40,8 @@ export interface PetState {
   [key: string]: unknown;
 }
 export interface LifeReport {
+  /** Metadata-triggered visual cue only. No host input or approval authority. */
+  attention: {kind: 'approval' | 'input'; side: 'left' | 'right'; phase: 'queued' | 'showing'} | null;
   /** Last selected autonomous episode; null before the first decision. */
   episode: string | null;
   intent: string;
@@ -93,6 +95,10 @@ export interface Pet {
   needsFrame(options: FrameOptions): boolean;
   /** False when busy or cooling down. */
   interact(kind: 'ball' | 'treat' | 'tug'): boolean;
+  /** False during direct play/feeding or another cue. Does not operate the host. */
+  notify(notice: {kind: 'approval' | 'input'; side?: 'left' | 'right'}): boolean;
+  /** Cancel the cue, preserving any in-progress connected pose recovery. */
+  clearNotice(): void;
   /** Sets the next throw's return style. Does not interrupt a fetch in progress. */
   setReturnStyle(style: FetchReturnStyle): FetchReturnStyle;
   readonly disposed: boolean;

package/retrieviewer.mjs

@@ -167,6 +167,9 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
   },
   // 'ball' | 'treat' | 'tug'. False when busy or cooling down; unknown kinds throw.
   interact(kind){alive();if(!INTERACTIONS.includes(kind))throw TypeError(`Unknown interaction: ${kind}`);return life.interact(kind);},
+  // A bounded visual cue only; never clicks, types, focuses or approves anything.
+  notify(notice){alive();return life.notify(notice);},
+  clearNotice(){alive();life.clearNotice();},
   // Applies to the next ball throw; never rewrites a fetch already in motion.
   setReturnStyle(style){alive();return life.setReturnStyle(style);},
   get disposed(){return disposed;},