tricu

io-v2-output.ts (3327B)

---

 // Presentation only. Byte acceptance and strict source UTF-8 Results are separate.
 // No evaluator handles, host callbacks, IO acknowledgements or terminal escapes.
 import { decodeUTF8, UTF8Error } from './io-v2-utf8.js';
 export type OutputStream = 'output' | 'error';
 export type OutputToken = { kind: 'text'; offset: number; text: string } |
   { kind: 'bytes'; offset: number; bytes: number[]; reason: 'invalid' | 'incomplete' | 'pending' };
 export interface OutputView { bytes: number[]; hex: string; tokens: OutputToken[] }
 
 function view(bytes: number[], final: boolean): OutputView {
   const tokens: OutputToken[] = [];
   for (let offset = 0; offset < bytes.length;) {
     const lead = bytes[offset]!;
     const width = lead <= 0x7f ? 1 : lead >= 0xc2 && lead <= 0xdf ? 2 :
       lead >= 0xe0 && lead <= 0xef ? 3 : lead >= 0xf0 && lead <= 0xf4 ? 4 : 1;
     const candidate = bytes.slice(offset, offset + width);
     try {
       const decoded = decodeUTF8(candidate, false);
       if (decoded.carry.length) {
         tokens.push({ kind: 'bytes', offset, bytes: candidate, reason: final ? 'incomplete' : 'pending' });
         break;
       }
       const previous = tokens.at(-1);
       if (previous?.kind === 'text') previous.text += decoded.text;
       else tokens.push({ kind: 'text', offset, text: decoded.text });
       offset += width;
     } catch (error) {
       if (!(error instanceof UTF8Error)) throw error;
       // Escape one offending byte; reconsider following bytes independently.
       // Thus invalid prefixes cannot swallow subsequent valid text.
       tokens.push({ kind: 'bytes', offset, bytes: [lead], reason: 'invalid' });
       offset++;
     }
   }
   return { bytes, hex: bytes.map(b => b.toString(16).padStart(2, '0')).join(' '), tokens };
 }
 
 // Owned by one UI run. The session separately enforces attempted-output budgets;
 // this buffer bounds retained accepted bytes, without refunds or history.
 export class OutputBuffer {
   private readonly streams: Record<OutputStream, number[]> = { output: [], error: [] };
   private size = 0;
   private ended = false;
   constructor(readonly limit = 16384) {
     if (!Number.isSafeInteger(limit) || limit < 0 || limit > 16384) throw new Error('invalid output limit');
   }
   append(stream: OutputStream, bytes: readonly number[]): void {
     if (this.ended) throw new Error('output presentation ended');
     if (stream !== 'output' && stream !== 'error') throw new Error('invalid output stream');
     if (!Array.isArray(bytes) || bytes.length === 0 || bytes.length > 4096) throw new Error('invalid output bytes');
     for (const byte of bytes) if (!Number.isInteger(byte) || byte < 0 || byte > 255) throw new Error('invalid output bytes');
     if (bytes.length > this.limit - this.size) throw new Error('output presentation limit');
     this.streams[stream].push(...bytes); this.size += bytes.length;
   }
   // End-of-presentation, including after structured cancellation, not closing a
   // borrowed stream. Incomplete suffixes become visible bytes, never IO failures.
   finish(): void { this.ended = true; }
   snapshot(): { done: boolean; size: number; output: OutputView; error: OutputView } {
     return { done: this.ended, size: this.size,
       output: view([...this.streams.output], this.ended), error: view([...this.streams.error], this.ended) };
   }
 }