@animalabs/agent-framework 0.23.1 → 0.24.0

package/src/code-execution/isolate/frames.ts

@@ -0,0 +1,209 @@
+/**
+ * Length-prefixed frames between a script's parent and its child: four bytes
+ * of big-endian length, then that many bytes of body. The parent writes to the
+ * child's stdin and reads the child's fd 3.
+ *
+ * A body's first byte says what it holds:
+ * - `JSON_KIND`: a message as UTF-8 JSON. Every frame from a child is one.
+ * - `RESULT_KIND`: a call's result for the guest, from the parent: whether it
+ *   resolves or rejects, the call's id, and the result's JSON as UTF-8 bytes,
+ *   which the child hands the engine as they are, with no second parse and no
+ *   string copy (the path the memory budget was measured on).
+ *
+ * The decoder is the only way bytes from a child become values in the parent,
+ * so it bounds what a child can make the parent hold: a frame longer than its
+ * limit, of a kind it doesn't take, not JSON, or holding more values than its
+ * limit (counted before it's parsed), is a protocol error, and the parent ends
+ * the script as crashed rather than reading on.
+ */
+
+/** The largest frame from a child: a call's arguments or a batch of output. */
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+
+const HEADER_BYTES = 4;
+export const JSON_KIND = 0;
+export const RESULT_KIND = 1;
+/** A result body's own header: its kind, `ok`, and the call's id. */
+const RESULT_HEADER_BYTES = 1 + 1 + 4;
+
+/** A frame that breaks the protocol: too long, of a kind not taken, not UTF-8, not JSON, holding too many values, or cut off when its stream ended. */
+export class FrameError extends Error {
+  /** For a frame too long to encode: how long its body came to. */
+  readonly bytes: number | undefined;
+
+  constructor(message: string, bytes?: number) {
+    super(message);
+    this.name = 'FrameError';
+    this.bytes = bytes;
+  }
+}
+
+/**
+ * The values in a JSON text, counted outside its strings: the top value, and
+ * each value inside an object or array. Counting stops once past `stopAfter`.
+ */
+export function countJsonValues(text: string, stopAfter = Infinity): number {
+  let values = 1;
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (inString) {
+      if (c === 0x5c) i++;
+      else if (c === 0x22) inString = false;
+    } else if (c === 0x22) {
+      inString = true;
+    } else if (c === 0x7b || c === 0x5b) {
+      // An object or array holds a first value unless it closes at once.
+      let j = i + 1;
+      while (j < text.length && (text.charCodeAt(j) === 0x20 || text.charCodeAt(j) === 0x0a || text.charCodeAt(j) === 0x0d || text.charCodeAt(j) === 0x09)) j++;
+      const next = text.charCodeAt(j);
+      if (next !== 0x7d && next !== 0x5d && ++values > stopAfter) return values;
+    } else if (c === 0x2c) {
+      if (++values > stopAfter) return values;
+    }
+  }
+  return values;
+}
+
+/** A call's result as the child decodes it: the JSON's bytes, untouched. */
+export interface ResultFrame {
+  t: 'result';
+  id: number;
+  ok: boolean;
+  json: Uint8Array;
+}
+
+function frame(body: Buffer, maxFrameBytes: number): Buffer {
+  if (body.length > maxFrameBytes) {
+    throw new FrameError(`a frame of ${body.length} bytes is longer than the ${maxFrameBytes} the protocol allows`, body.length);
+  }
+  const out = Buffer.allocUnsafe(HEADER_BYTES + body.length);
+  out.writeUInt32BE(body.length, 0);
+  body.copy(out, HEADER_BYTES);
+  return out;
+}
+
+/** One message as a JSON frame. One longer than `maxFrameBytes` throws a FrameError, and nothing is written. */
+export function encodeFrame(message: unknown, maxFrameBytes: number = MAX_FRAME_BYTES): Buffer {
+  const json = JSON.stringify(message);
+  if (json === undefined) throw new FrameError('a frame must hold a JSON value');
+  const body = Buffer.allocUnsafe(1 + Buffer.byteLength(json, 'utf8'));
+  body[0] = JSON_KIND;
+  body.write(json, 1, 'utf8');
+  return frame(body, maxFrameBytes);
+}
+
+/**
+ * A call's result as a result frame: the JSON's bytes follow a header of `ok`
+ * and the id. Written straight into the frame, so a result's bytes are held
+ * once, which the host's memory figure counts.
+ */
+export function encodeResultFrame(id: number, ok: boolean, json: string, maxFrameBytes: number): Buffer {
+  const bodyLength = RESULT_HEADER_BYTES + Buffer.byteLength(json, 'utf8');
+  if (bodyLength > maxFrameBytes) {
+    throw new FrameError(`a frame of ${bodyLength} bytes is longer than the ${maxFrameBytes} the protocol allows`, bodyLength);
+  }
+  const out = Buffer.allocUnsafe(HEADER_BYTES + bodyLength);
+  out.writeUInt32BE(bodyLength, 0);
+  out[HEADER_BYTES] = RESULT_KIND;
+  out[HEADER_BYTES + 1] = ok ? 1 : 0;
+  out.writeUInt32BE(id >>> 0, HEADER_BYTES + 2);
+  out.write(json, HEADER_BYTES + RESULT_HEADER_BYTES, 'utf8');
+  return out;
+}
+
+/** How much a result frame's body holds beyond its JSON. */
+export const RESULT_FRAME_OVERHEAD = RESULT_HEADER_BYTES;
+
+/**
+ * Bytes in, whole frames' values out. Holds at most one frame's bytes plus its
+ * header: a header naming more than `maxFrameBytes` throws before any of that
+ * frame's body is kept, and once a header names its body's length, the body
+ * is one buffer of that length, which each chunk is copied into. So however
+ * the bytes arrive, one at a time included, the decoder keeps no chunk of
+ * them. Takes result frames only if asked to: a parent's decoder takes JSON
+ * alone.
+ */
+export class FrameDecoder {
+  private readonly header = Buffer.alloc(HEADER_BYTES);
+  private headerFilled = 0;
+  private body: Buffer | null = null;
+  private bodyFilled = 0;
+  private broken: FrameError | null = null;
+
+  constructor(
+    private readonly maxFrameBytes: number = MAX_FRAME_BYTES,
+    private readonly takesResults = false,
+    /** The most values a JSON frame may hold, counted before it's parsed. */
+    private readonly maxValues = Infinity,
+  ) {}
+
+  /** The values of every frame `chunk` completes, in order. Throws the same FrameError from then on, once one frame was bad. */
+  push(chunk: Buffer): unknown[] {
+    if (this.broken) throw this.broken;
+    const values: unknown[] = [];
+    let at = 0;
+    while (at < chunk.length) {
+      if (this.body === null) {
+        const n = Math.min(HEADER_BYTES - this.headerFilled, chunk.length - at);
+        chunk.copy(this.header, this.headerFilled, at, at + n);
+        this.headerFilled += n;
+        at += n;
+        if (this.headerFilled < HEADER_BYTES) break;
+        const length = this.header.readUInt32BE(0);
+        if (length > this.maxFrameBytes) {
+          return this.fail(`a frame announced ${length} bytes, more than the ${this.maxFrameBytes} the protocol allows`);
+        }
+        if (length === 0) return this.fail('a frame was empty');
+        this.body = Buffer.allocUnsafe(length);
+        this.bodyFilled = 0;
+      }
+      const n = Math.min(this.body.length - this.bodyFilled, chunk.length - at);
+      chunk.copy(this.body, this.bodyFilled, at, at + n);
+      this.bodyFilled += n;
+      at += n;
+      if (this.bodyFilled < this.body.length) break;
+      const body = this.body;
+      this.body = null;
+      this.headerFilled = 0;
+      values.push(this.decode(body));
+    }
+    return values;
+  }
+
+  /** At the stream's end: throws if a frame was begun and not finished. */
+  end(): void {
+    if (this.broken) throw this.broken;
+    if (this.headerFilled > 0 || this.body !== null) {
+      this.fail(`the stream ended inside a frame, with ${this.body === null ? this.headerFilled : this.bodyFilled} of its bytes read`);
+    }
+  }
+
+  private decode(body: Buffer): unknown {
+    if (body[0] === RESULT_KIND && this.takesResults) {
+      if (body.length < RESULT_HEADER_BYTES) return this.fail('a result frame was shorter than its header');
+      const result: ResultFrame = { t: 'result', id: body.readUInt32BE(2), ok: body[1] === 1, json: body.subarray(RESULT_HEADER_BYTES) };
+      return result;
+    }
+    if (body[0] !== JSON_KIND) return this.fail(`a frame was of kind ${body[0]}, which this side doesn't take`);
+    let text: string;
+    try {
+      // A byte-order mark is kept, so it fails JSON.parse as the text it is.
+      text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(body.subarray(1));
+    } catch {
+      return this.fail('a frame was not UTF-8');
+    }
+    if (countJsonValues(text, this.maxValues) > this.maxValues) return this.fail(`a frame held more than ${this.maxValues} values`);
+    try {
+      return JSON.parse(text);
+    } catch {
+      return this.fail('a frame was not JSON');
+    }
+  }
+
+  private fail(message: string): never {
+    this.broken = new FrameError(message);
+    this.body = null;
+    throw this.broken;
+  }
+}

package/src/code-execution/isolate/output.ts

@@ -0,0 +1,161 @@
+/**
+ * A script's output, bounded once, in the parent: every return, whether a
+ * yield, a wait or the ending's, gives what the script wrote since the
+ * previous one, its first and last characters within the bound and a count of
+ * what was dropped between. A long stretch keeps its start, since that's
+ * often where its trouble began, such as the first error before a cascade.
+ *
+ * The child can't know when the parent returns, since its frames reach it only
+ * while its guest is idle, so the bound sits in the parent: the child holds
+ * one bounded batch of what the guest writes and flushes it, and the parent
+ * keeps the head and tail of each return's stretch, starting both afresh at
+ * each return. Memory is bounded by construction on both sides; the price is
+ * that a printing loop's whole output crosses the pipe, in batches.
+ */
+
+export interface OutputBounds {
+  /** Characters kept from the start of each return's stretch. */
+  headChars: number;
+  /** Characters kept from its end. */
+  tailChars: number;
+}
+
+export const DEFAULT_OUTPUT_BOUNDS: OutputBounds = { headChars: 8_000, tailChars: 8_000 };
+
+/** The most one output frame carries, so a single large write is sent in pieces. */
+export const MAX_BATCH_CHARS = 64 * 1024;
+
+/** Where to cut `text` near `at` without parting a surrogate pair: one earlier if `at` falls inside one. */
+function safeCut(text: string, at: number): number {
+  if (at <= 0 || at >= text.length) return Math.max(0, Math.min(at, text.length));
+  const before = text.charCodeAt(at - 1);
+  return before >= 0xd800 && before <= 0xdbff ? at - 1 : at;
+}
+
+/** The child's side: what the guest wrote since the last flush, at most a batch of it at a time. */
+export class OutputBatch {
+  private pending: string[] = [];
+  private size = 0;
+
+  /** Characters waiting to be flushed. */
+  get unflushed(): number {
+    return this.size;
+  }
+
+  /** True once the batch is full, so the caller flushes now. */
+  write(text: string): boolean {
+    if (text.length === 0) return this.size >= MAX_BATCH_CHARS;
+    this.pending.push(text);
+    this.size += text.length;
+    return this.size >= MAX_BATCH_CHARS;
+  }
+
+  /** The waiting text in pieces of at most a batch each, emptying it; empty when nothing waits. */
+  flush(): string[] {
+    if (this.size === 0) return [];
+    let text = this.pending.join('');
+    this.pending = [];
+    this.size = 0;
+    const pieces: string[] = [];
+    while (text.length > MAX_BATCH_CHARS) {
+      const cut = safeCut(text, MAX_BATCH_CHARS);
+      pieces.push(text.slice(0, cut));
+      text = text.slice(cut);
+    }
+    if (text.length > 0) pieces.push(text);
+    return pieces;
+  }
+}
+
+/** A return's stretch of output: its head and tail, and the count dropped between them. */
+export interface OutputWindow {
+  head: string;
+  tail: string;
+  dropped: number;
+}
+
+/** The line naming what was dropped, at its longest, as renderOutput puts it between the head and the tail. */
+const DROPPED_LINE_CHARS = `\n[… ${Number.MAX_SAFE_INTEGER} characters of output dropped here …]\n`.length;
+
+/**
+ * The stretch as the model sees it: the head, a line naming what was dropped
+ * if anything was, and the tail. Past `max`, its start and its end are cut
+ * alike to fit it, each taking the room the other doesn't need, and the count
+ * takes in what they gave up, so a return held to its agent's inline cap
+ * still shows both ends. A `max` that leaves no room for that line gets the
+ * line alone, which passes it.
+ */
+export function renderOutput(w: OutputWindow, max = Infinity): string {
+  const whole = w.dropped === 0 ? w.head + w.tail : `${w.head}\n[… ${w.dropped} characters of output dropped here …]\n${w.tail}`;
+  if (whole.length <= max) return whole;
+  const room = Math.max(0, Math.floor(max) - DROPPED_LINE_CHARS);
+  // With nothing dropped yet, the head and the tail are one stretch, whose end
+  // lies in the head while the tail is short or empty: it's cut as one.
+  const [first, last] = w.dropped === 0 ? [whole, whole] : [w.head, w.tail];
+  const lastKeep = Math.min(last.length, Math.max(Math.floor(room / 2), room - first.length));
+  const head = first.slice(0, safeCut(first, Math.min(first.length, room - lastKeep)));
+  // Kept from the end, never starting on a pair's second half.
+  let from = last.length - lastKeep;
+  const at = last.charCodeAt(from);
+  if (from > 0 && at >= 0xdc00 && at <= 0xdfff) from += 1;
+  const tail = last.slice(from);
+  const dropped = w.dropped === 0 ? whole.length - head.length - tail.length : w.dropped + (first.length - head.length) + from;
+  return `${head}\n[… ${dropped} characters of output dropped here …]\n${tail}`;
+}
+
+/** The parent's side: the head and tail of what arrived since the last return, and the count dropped between. */
+export class WindowOutput {
+  private head = '';
+  private tail = '';
+  private dropped = 0;
+
+  constructor(private readonly bounds: OutputBounds) {}
+
+  /** Add text the child flushed. */
+  apply(text: string): void {
+    let rest = text;
+    if (this.tail.length === 0 && this.dropped === 0) {
+      const room = this.bounds.headChars - this.head.length;
+      if (room > 0) {
+        const cut = safeCut(rest, room);
+        this.head += rest.slice(0, cut);
+        rest = rest.slice(cut);
+        if (rest.length === 0) return;
+      }
+    }
+    this.tail += rest;
+    const over = this.tail.length - this.bounds.tailChars;
+    if (over > 0) {
+      // Drop from the front, never splitting a pair: the cut moves later by one if it would.
+      let cut = over;
+      const at = this.tail.charCodeAt(cut - 1);
+      if (at >= 0xd800 && at <= 0xdbff) cut += 1;
+      this.dropped += cut;
+      this.tail = this.tail.slice(cut);
+    }
+  }
+
+  /** Characters dropped from the stretch so far. */
+  get droppedChars(): number {
+    return this.dropped;
+  }
+
+  /** The stretch as it stands. */
+  window(): OutputWindow {
+    return { head: this.head, tail: this.tail, dropped: this.dropped };
+  }
+
+  /** The stretch as the model sees it, whole (renderOutput). */
+  render(): string {
+    return renderOutput(this.window());
+  }
+
+  /** The stretch, and a fresh one from here. */
+  take(): OutputWindow {
+    const window = this.window();
+    this.head = '';
+    this.tail = '';
+    this.dropped = 0;
+    return window;
+  }
+}