@teaflask/assistant 0.0.0 → 0.3.0

package/src/reader/layout-probe.ts

@@ -0,0 +1,166 @@
+// The reader's one window onto layout and computed style. Every
+// getComputedStyle / getBoundingClientRect / viewport read in the reader
+// goes through this interface — nothing else may touch those APIs — so
+// the walk's structural logic unit-tests under jsdom (which has no
+// layout engine) with a fake probe, while the browser probe stays a thin
+// adapter exercised by the live lanes.
+
+export interface StyleSlice {
+  display: string;
+  visibility: string;
+  opacity: string;
+  cursor: string;
+  overflowX: string;
+  overflowY: string;
+}
+
+export interface RectSlice {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+export interface SizeSlice {
+  width: number;
+  height: number;
+}
+
+export interface LayoutProbe {
+  styleOf(element: Element): StyleSlice;
+  /** The rendered text of a ::before/::after pseudo-element, or "". */
+  pseudoContentOf(element: Element, pseudo: "::before" | "::after"): string;
+  rectOf(element: Element): RectSlice;
+  /** Layout box size (offsetWidth/offsetHeight); -1 when unknowable. */
+  offsetSizeOf(element: Element): SizeSlice;
+  viewportSizeOf(): SizeSlice;
+  /**
+   * The engine's own visibility verdict (checkVisibility), or null when
+   * the engine does not offer one.
+   */
+  nativeVisibilityOf(element: Element): boolean | null;
+}
+
+const DEFAULT_STYLE: StyleSlice = {
+  display: "block",
+  visibility: "visible",
+  opacity: "1",
+  cursor: "auto",
+  overflowX: "visible",
+  overflowY: "visible",
+};
+
+const ZERO_RECT: RectSlice = {
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  width: 0,
+  height: 0,
+};
+
+/** The real-browser probe. Every read is fenced — cross-origin style
+ * access and detached nodes throw in some engines, and a probe failure
+ * must never fail a snapshot. */
+export function browserLayoutProbe(): LayoutProbe {
+  return {
+    styleOf(element) {
+      try {
+        const style = window.getComputedStyle(element);
+        return {
+          display: style.display,
+          visibility: style.visibility,
+          opacity: style.opacity,
+          cursor: style.cursor,
+          overflowX: style.overflowX,
+          overflowY: style.overflowY,
+        };
+      } catch {
+        return DEFAULT_STYLE;
+      }
+    },
+    pseudoContentOf(element, pseudo) {
+      try {
+        const style = window.getComputedStyle(element, pseudo);
+        if (style.display === "none" || style.visibility === "hidden") {
+          return "";
+        }
+        return pseudoTextFromContentValue(style.content);
+      } catch {
+        return "";
+      }
+    },
+    rectOf(element) {
+      try {
+        const rect = element.getBoundingClientRect();
+        return {
+          top: rect.top,
+          left: rect.left,
+          right: rect.right,
+          bottom: rect.bottom,
+          width: rect.width,
+          height: rect.height,
+        };
+      } catch {
+        return ZERO_RECT;
+      }
+    },
+    offsetSizeOf(element) {
+      if (element instanceof HTMLElement) {
+        return { width: element.offsetWidth, height: element.offsetHeight };
+      }
+      return { width: -1, height: -1 };
+    },
+    viewportSizeOf() {
+      return { width: window.innerWidth, height: window.innerHeight };
+    },
+    nativeVisibilityOf(element) {
+      if (typeof element.checkVisibility !== "function") {
+        return null;
+      }
+      try {
+        return element.checkVisibility({
+          checkOpacity: true,
+          checkVisibilityCSS: true,
+        });
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * The text a CSS content value renders: its quoted string tokens,
+ * unescaped and joined. "none"/"normal" and non-string values (counters,
+ * url()) render nothing the reader can use.
+ */
+function pseudoTextFromContentValue(content: string): string {
+  if (content === "" || content === "none" || content === "normal") {
+    return "";
+  }
+  const tokens = content.match(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g);
+  if (tokens === null) {
+    return "";
+  }
+  return tokens
+    .map((token) => _unescapedCssString(token.slice(1, -1)))
+    .join("");
+}
+
+function _unescapedCssString(text: string): string {
+  return text.replace(/\\(.)/g, (_match, escaped: string) => {
+    if (escaped === "n") {
+      return "\n";
+    }
+    if (escaped === "r") {
+      return "\r";
+    }
+    if (escaped === "t") {
+      return "\t";
+    }
+    return escaped;
+  });
+}

package/src/reader/line-diff.ts

@@ -0,0 +1,168 @@
+// A minimal unified line diff (Myers shortest-edit), so a repeat page
+// read can ride as "what changed since your last read" instead of the
+// whole tree. Output is the familiar hunk format — `@@ -a,b +c,d @@`
+// headers, three lines of context, no file header — because the model
+// already knows how to read it. Pure text in, pure text out.
+
+const CONTEXT_LINES = 3;
+
+interface EditOp {
+  tag: "equal" | "delete" | "insert";
+  text: string;
+}
+
+/** The unified diff from before to after; "" when the texts are equal. */
+export function unifiedDiffOf(before: string, after: string): string {
+  if (before === after) {
+    return "";
+  }
+  const beforeLines = before.split("\n");
+  const afterLines = after.split("\n");
+  const ops = _editOpsOf(beforeLines, afterLines);
+  return _hunksOf(ops).join("\n");
+}
+
+function _editOpsOf(before: string[], after: string[]): EditOp[] {
+  const trace = _shortestEditTraceOf(before, after);
+  return _backtrackedOpsOf(trace, before, after);
+}
+
+function _shortestEditTraceOf(before: string[], after: string[]): number[][] {
+  const n = before.length;
+  const m = after.length;
+  const max = n + m;
+  const offset = max;
+  const v: number[] = new Array<number>(2 * max + 2).fill(0);
+  const trace: number[][] = [];
+  for (let d = 0; d <= max; d += 1) {
+    trace.push(v.slice());
+    for (let k = -d; k <= d; k += 2) {
+      let x: number;
+      if (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])) {
+        x = v[offset + k + 1];
+      } else {
+        x = v[offset + k - 1] + 1;
+      }
+      let y = x - k;
+      while (x < n && y < m && before[x] === after[y]) {
+        x += 1;
+        y += 1;
+      }
+      v[offset + k] = x;
+      if (x >= n && y >= m) {
+        return trace;
+      }
+    }
+  }
+  return trace;
+}
+
+function _backtrackedOpsOf(
+  trace: number[][],
+  before: string[],
+  after: string[],
+): EditOp[] {
+  const offset = before.length + after.length;
+  const reversed: EditOp[] = [];
+  let x = before.length;
+  let y = after.length;
+  for (let d = trace.length - 1; d >= 0 && (x > 0 || y > 0); d -= 1) {
+    const v = trace[d];
+    const k = x - y;
+    let previousK: number;
+    if (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])) {
+      previousK = k + 1;
+    } else {
+      previousK = k - 1;
+    }
+    const previousX = v[offset + previousK];
+    const previousY = previousX - previousK;
+    while (x > previousX && y > previousY) {
+      reversed.push({ tag: "equal", text: before[x - 1] });
+      x -= 1;
+      y -= 1;
+    }
+    if (d > 0) {
+      if (x === previousX) {
+        reversed.push({ tag: "insert", text: after[y - 1] });
+        y -= 1;
+      } else {
+        reversed.push({ tag: "delete", text: before[x - 1] });
+        x -= 1;
+      }
+    }
+  }
+  return reversed.reverse();
+}
+
+function _hunksOf(ops: EditOp[]): string[] {
+  const groups = _changeGroupsOf(ops);
+  const lines: string[] = [];
+  // Running line numbers (1-indexed) per op index, computed as we walk.
+  let aLine = 1;
+  let bLine = 1;
+  let opIndex = 0;
+  for (const group of groups) {
+    while (opIndex < group.start) {
+      const op = ops[opIndex];
+      if (op.tag !== "insert") {
+        aLine += 1;
+      }
+      if (op.tag !== "delete") {
+        bLine += 1;
+      }
+      opIndex += 1;
+    }
+    let aCount = 0;
+    let bCount = 0;
+    const body: string[] = [];
+    for (let index = group.start; index < group.end; index += 1) {
+      const op = ops[index];
+      if (op.tag === "equal") {
+        body.push(` ${op.text}`);
+        aCount += 1;
+        bCount += 1;
+      } else if (op.tag === "delete") {
+        body.push(`-${op.text}`);
+        aCount += 1;
+      } else {
+        body.push(`+${op.text}`);
+        bCount += 1;
+      }
+    }
+    lines.push(
+      `@@ -${String(aLine)},${String(aCount)} +${String(bLine)},${String(bCount)} @@`,
+      ...body,
+    );
+    while (opIndex < group.end) {
+      const op = ops[opIndex];
+      if (op.tag !== "insert") {
+        aLine += 1;
+      }
+      if (op.tag !== "delete") {
+        bLine += 1;
+      }
+      opIndex += 1;
+    }
+  }
+  return lines;
+}
+
+function _changeGroupsOf(ops: EditOp[]): { start: number; end: number }[] {
+  const changeIndexes = ops
+    .map((op, index) => (op.tag === "equal" ? -1 : index))
+    .filter((index) => index >= 0);
+  const groups: { start: number; end: number }[] = [];
+  for (const changeIndex of changeIndexes) {
+    const start = Math.max(0, changeIndex - CONTEXT_LINES);
+    const end = Math.min(ops.length, changeIndex + CONTEXT_LINES + 1);
+    const last = groups[groups.length - 1] as
+      { start: number; end: number } | undefined;
+    if (last !== undefined && start <= last.end) {
+      last.end = Math.max(last.end, end);
+    } else {
+      groups.push({ start, end });
+    }
+  }
+  return groups;
+}

package/src/reader/read-page.ts

@@ -0,0 +1,240 @@
+// One builtin.read_page request in, one landable result out: snapshot
+// the page the mount lives in, render it, fit it under the tool-results
+// door's size cap, and — on a repeat read — deliver the unified diff
+// against the previous read when that is the cheaper payload. The
+// baseline lives here at module level, per thread: the handler map's
+// identity churns with its React deps, and a baseline that died on every
+// re-render would never produce a diff. An empty diff (is_diff with ""
+// content) means the page is unchanged since the previous read.
+
+import { boundedTextOf, doorCostOfText } from "../transport/door-budget.js";
+import type { LayoutProbe } from "./layout-probe.js";
+import { unifiedDiffOf } from "./line-diff.js";
+import { pageHeaderOf, renderedTreeOf } from "./render.js";
+import {
+  DEFAULT_MAX_DEPTH,
+  resolvedSnapshotRootOf,
+  snapshotTreeOf,
+  type SnapshotOptions,
+} from "./snapshot.js";
+
+// The content budget under the door's 20k serialized cap, measured in
+// the door's own metric (door-budget.ts): 16k leaves headroom for the
+// result's url/title/flag siblings, mirroring the action-response bound.
+const READ_PAGE_CONTENT_MAX_CHARS = 16_000;
+// When the full-depth tree overflows, re-render shallower until it fits.
+const DEPTH_LADDER = [30, 20, 12, 8, 5, 3];
+const TRUNCATION_NOTICE = "… [truncated: the page holds more than fits here]";
+const MAX_TITLE_LENGTH = 300;
+const MAX_URL_LENGTH = 2_000;
+
+/** The wire shape of ReadPageResult, synthesized package-side. */
+export interface ReadPageReport {
+  url: string;
+  title: string;
+  content: string;
+  is_diff: boolean;
+  truncated: boolean;
+}
+
+/**
+ * An expected, recoverable read refusal — a stale ref, a selector that
+ * matches nothing, a page with no body yet. Its message is the reader's
+ * own model-actionable sentence (usually "take a fresh full read"), and
+ * the handler delivers it verbatim: wrapping it in give-up prose would
+ * cancel the retry the sentence asks for. A reader crash is anything
+ * else.
+ */
+export class SnapshotUnavailableError extends Error {}
+
+// A diff only means "what changed" against the SAME view: the baseline
+// remembers the scope (knobs) that produced it AND the shape the fitter
+// actually rendered (full, which ladder rung, or line-bounded). A read
+// with any other scope starts fresh — otherwise two differently-scoped
+// reads whose text happens to coincide would answer "nothing changed",
+// and an overlapping scope would present scoping as removals. A read at
+// any other shape starts fresh too — the scope holds the REQUESTED
+// depth, so a page growing past the size cap between two identical
+// requests shifts the ladder rung, and diffing across the shift would
+// present depth-truncated sections as removed from the page.
+interface ReadBaseline {
+  scope: string;
+  shape: string;
+  text: string;
+}
+
+const _baselineByThread = new Map<string, ReadBaseline>();
+
+export function readPageResultOf(
+  threadId: string,
+  action: Record<string, unknown> | null,
+  probe: LayoutProbe,
+): ReadPageReport {
+  const request = _readRequestOf(action, probe);
+  const scope = _scopeKeyOf(request);
+  const fitted = _fittedTreeTextOf(request);
+  const content = _cheaperOfDiffAndFull(threadId, scope, fitted);
+  _baselineByThread.set(threadId, {
+    scope,
+    shape: fitted.shape,
+    text: fitted.text,
+  });
+  return {
+    url: boundedTextOf(document.location.href, MAX_URL_LENGTH),
+    title: boundedTextOf(
+      document.title.replace(/\s+/g, " ").trim(),
+      MAX_TITLE_LENGTH,
+    ),
+    content: content.text,
+    is_diff: content.isDiff,
+    truncated: fitted.truncated,
+  };
+}
+
+export function _resetBaselinesForTests(): void {
+  _baselineByThread.clear();
+}
+
+function _readRequestOf(
+  action: Record<string, unknown> | null,
+  probe: LayoutProbe,
+): SnapshotOptions {
+  // Wire defense only: the knobs are model-supplied and optional, and a
+  // wrong-typed knob degrades to its default rather than failing a read.
+  return {
+    probe,
+    ignoreSelectors: _stringListOf(action?.ignore_selectors),
+    maxDepth: _depthOf(action?.max_depth),
+    interactive: action?.interactive === true,
+    showHidden: action?.show_hidden === true,
+    selector: _nonEmptyStringOf(action?.selector),
+    refId: _nonEmptyStringOf(action?.ref_id),
+    rootElement: null,
+  };
+}
+
+interface FittedTree {
+  text: string;
+  truncated: boolean;
+  /** What the fitter actually rendered: "full", "depth:N", "line-bounded". */
+  shape: string;
+}
+
+function _fittedTreeTextOf(request: SnapshotOptions): FittedTree {
+  // Resolve the root once and pin the element: the ladder below renders
+  // the same read several times, each render rebuilds the ref registry,
+  // and a ref whose element changed identity since minting would resolve
+  // on the first render and be gone by the second — a read must not fail
+  // on payload size where the same request succeeds when small.
+  const rooting = resolvedSnapshotRootOf(request);
+  if (rooting.error !== null) {
+    throw new SnapshotUnavailableError(rooting.error);
+  }
+  const pinned: SnapshotOptions = { ...request, rootElement: rooting.root };
+  const header = pageHeaderOf(document.title, document.location.href);
+  const fullText = `${header}\n${_renderedSnapshotOf(pinned)}`;
+  if (doorCostOfText(fullText) <= READ_PAGE_CONTENT_MAX_CHARS) {
+    return { text: fullText, truncated: false, shape: "full" };
+  }
+  for (const rung of DEPTH_LADDER) {
+    if (rung >= pinned.maxDepth) {
+      continue;
+    }
+    const shallower = `${header}\n${_renderedSnapshotOf({ ...pinned, maxDepth: rung })}`;
+    if (doorCostOfText(shallower) <= READ_PAGE_CONTENT_MAX_CHARS) {
+      return {
+        text: shallower,
+        truncated: true,
+        shape: `depth:${String(rung)}`,
+      };
+    }
+  }
+  // Even the shallowest rung overflows: deliver the full outline cut on
+  // line boundaries. Re-render it first so the ref registry matches the
+  // refs this outline shows — every ladder rung above rebuilt the registry
+  // as it ran, so it currently holds the shallowest rung's refs, not the
+  // deep ones a ref_id follow-up read would look up. Refs are stable, so
+  // this reproduces fullText exactly while restoring the full registry.
+  const fullTextAgain = `${header}\n${_renderedSnapshotOf(pinned)}`;
+  return {
+    text: _lineBoundedTextOf(fullTextAgain),
+    truncated: true,
+    shape: "line-bounded",
+  };
+}
+
+function _renderedSnapshotOf(request: SnapshotOptions): string {
+  const outcome = snapshotTreeOf(request);
+  if (outcome.error !== null) {
+    throw new SnapshotUnavailableError(outcome.error);
+  }
+  return renderedTreeOf(outcome.tree);
+}
+
+function _cheaperOfDiffAndFull(
+  threadId: string,
+  scope: string,
+  fitted: FittedTree,
+): { text: string; isDiff: boolean } {
+  const baseline = _baselineByThread.get(threadId);
+  if (baseline?.scope !== scope || baseline.shape !== fitted.shape) {
+    return { text: fitted.text, isDiff: false };
+  }
+  // Two line-bounded renders share a shape, but the cut point slides
+  // with any earlier change — tail sections would flap in and out of the
+  // diff as removals that never happened. Those reads deliver in full.
+  if (fitted.shape === "line-bounded") {
+    return { text: fitted.text, isDiff: false };
+  }
+  const diff = unifiedDiffOf(baseline.text, fitted.text);
+  if (doorCostOfText(diff) < doorCostOfText(fitted.text)) {
+    return { text: diff, isDiff: true };
+  }
+  return { text: fitted.text, isDiff: false };
+}
+
+function _scopeKeyOf(request: SnapshotOptions): string {
+  // Everything that shapes the rendered view except the probe — including
+  // the page itself: a client-side navigation keeps this module alive, and
+  // diffing the new page against the old one would read the old page's
+  // unique content as removals.
+  return JSON.stringify({
+    url: document.location.href,
+    interactive: request.interactive,
+    maxDepth: request.maxDepth,
+    showHidden: request.showHidden,
+    selector: request.selector,
+    refId: request.refId,
+    ignoreSelectors: request.ignoreSelectors,
+  });
+}
+
+function _lineBoundedTextOf(text: string): string {
+  const noticeCost = doorCostOfText(`\n${TRUNCATION_NOTICE}`);
+  const bounded = boundedTextOf(text, READ_PAGE_CONTENT_MAX_CHARS - noticeCost);
+  // Cut on a line boundary so the outline stays parseable to the end.
+  const lastLineBreak = bounded.lastIndexOf("\n");
+  const wholeLines =
+    lastLineBreak > 0 ? bounded.slice(0, lastLineBreak) : bounded;
+  return `${wholeLines}\n${TRUNCATION_NOTICE}`;
+}
+
+function _depthOf(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    return DEFAULT_MAX_DEPTH;
+  }
+  return Math.min(value, DEFAULT_MAX_DEPTH);
+}
+
+function _nonEmptyStringOf(value: unknown): string | null {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+function _stringListOf(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (member): member is string => typeof member === "string" && member !== "",
+  );
+}

package/src/reader/redaction.ts

@@ -0,0 +1,84 @@
+// What a text control's current value contributes to the snapshot — and
+// the always-on redaction gate in front of it. Passwords and fields
+// whose autocomplete declares a secret (card numbers, one-time codes)
+// never enter a snapshot; there is deliberately no way to turn this off.
+
+import { isContentEditableElement } from "./roles.js";
+
+export const REDACTED_VALUE = "[redacted]";
+
+const SENSITIVE_AUTOCOMPLETE_VALUES = new Set([
+  "cc-number",
+  "cc-csc",
+  "current-password",
+  "new-password",
+  "one-time-code",
+]);
+
+/**
+ * The value a textbox-like element shows, redacted where it must be:
+ * null when the element holds no readable value at all.
+ */
+export function textboxValueOf(element: Element): string | null {
+  if (isContentEditableElement(element)) {
+    // Not every engine implements innerText (jsdom); fall back honestly.
+    const rendered: unknown = Reflect.get(element, "innerText");
+    if (typeof rendered === "string") {
+      return rendered;
+    }
+    return element.textContent;
+  }
+  if (
+    !(element instanceof HTMLInputElement) &&
+    !(element instanceof HTMLTextAreaElement)
+  ) {
+    return null;
+  }
+  if (element instanceof HTMLInputElement) {
+    const type = element.type;
+    // hidden inputs hold machine state the user never sees — CSRF tokens,
+    // session blobs — so they never contribute a value, redacted or not
+    // (they surface at all only under show_hidden). checkbox/radio/file
+    // carry no readable text value either.
+    if (
+      type === "checkbox" ||
+      type === "radio" ||
+      type === "file" ||
+      type === "hidden"
+    ) {
+      return null;
+    }
+    if (type === "password") {
+      return element.value === "" ? "" : REDACTED_VALUE;
+    }
+  }
+  if (theFieldHoldsASecret(element) && element.value !== "") {
+    return REDACTED_VALUE;
+  }
+  return element.value;
+}
+
+/**
+ * Whether a field's autocomplete declares a secret (card numbers,
+ * passwords, one-time codes). One predicate for both directions: the
+ * snapshot redacts what it reads, and prefill refuses what it would
+ * write — the two guards must never disagree about what a secret is.
+ */
+export function theFieldHoldsASecret(
+  element: HTMLInputElement | HTMLTextAreaElement,
+): boolean {
+  const autocomplete = (element.getAttribute("autocomplete") ?? "")
+    .trim()
+    .toLowerCase();
+  if (autocomplete === "") {
+    return false;
+  }
+  // autocomplete is a token list ("billing cc-number"); any secret token
+  // marks the field, and every cc-exp variant counts.
+  return autocomplete
+    .split(/\s+/)
+    .some(
+      (token) =>
+        SENSITIVE_AUTOCOMPLETE_VALUES.has(token) || token.startsWith("cc-exp"),
+    );
+}