@yaag/extension 0.2.1 → 0.4.0

package/README.md

@@ -35,11 +35,25 @@ For a throwaway session instead: `pi -e ./packages/extension`.
 
 | Parameter | Type | Meaning |
 |---|---|---|
-| `file` | `string` | Path to the Orchestration Program file |
+| `file` | `string?` | Path to the Orchestration Program file |
+| `script` | `string?` | Orchestration Program source text (Inline Program) |
 | `args` | `string?` | The program's arguments, as a JSON object string |
 | `background` | `boolean?` | Start the Run in the background and return its Run id |
 | `record` | `string?` | Write this Run's Cassette artifact to this path |
-| `resume` | `string?` | Replay a matching Cassette prefix, then continue live |
+| `resume` | `string?` | Replay a matching Cassette prefix, then continue live; alone it resumes a stored Inline Program |
+
+Give `file` or `script`, and not both; a violation is a parameter error raised
+before any process starts. A `script` program can import `@yaag/runtime` and
+`typebox` only (ADR-0033). The source travels to the CLI on a descriptor, and
+never through the process argument list (`ps`, `/proc/<pid>/cmdline`), which
+every local user can read. The durable Run record keeps the source, so the
+record directory is `0700` and each record file is `0600`. To resume an inline
+Run, give `resume` and give no `file` and no `script`: yaag reads the source
+back from the Run record whose Checkpoint path matches, and gives it to the CLI
+again, so the program identity check keeps its meaning (ADR-0033). Give `script`
+again only to change the program. A Cassette that you
+ask for with `record` also embeds the source, and it is written owner-only,
+with mode `0600` (ADR-0021).
 
 Blocking by default: the call returns when the Run ends, and its content is the
 Run's return value. With `background: true` it returns at once with a short Run
@@ -194,7 +208,8 @@ bun apps/yaag/src/cli.ts run .yaag/review.ts
 and `yaag_run` are the same execution path. The extension spawns exactly this
 CLI as a child — `bun cli.ts run <file> --events-fd 3 --args <json>` — and reads
 structured Lifecycle Events from descriptor 3 while the CLI's own stderr format
-stays unchanged. **What you debug in a terminal is what the session runs.**
+stays unchanged. An Inline Program adds one inbound channel: the extension
+writes the source to descriptor 4, closes it, and names it as `--eval-fd 4`. **What you debug in a terminal is what the session runs.**
 
 ## How stopping works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.2.1",
-    "@yaag/runtime": "0.2.1",
-    "@yaag/tui": "0.2.1",
+    "@yaag/cli": "0.4.0",
+    "@yaag/runtime": "0.4.0",
+    "@yaag/tui": "0.4.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/cli-child.ts

@@ -1,6 +1,7 @@
-import { spawn } from "node:child_process";
+import { type StdioOptions, spawn } from "node:child_process";
 import type { Readable, Writable } from "node:stream";
 import { type ReapTarget, reap } from "@yaag/runtime";
+import { writeEvalSource } from "./eval-pipe.ts";
 import { StderrTail } from "./stderr-buffer.ts";
 
 /** The process-level output of one Bun CLI child. */
@@ -16,6 +17,12 @@ export interface CliChildOptions {
   readonly argv: readonly string[];
   /** Run reserves fd 3 for Lifecycle Events; ordinary CLI calls do not. */
   readonly events?: boolean;
+  /**
+   * The Inline Program source: written to fd 4 and closed there, because the
+   * CLI reads it with `--eval-fd 4` (ADR-0033). Fd 3 stays the Lifecycle Event
+   * stream, so this option implies `events`.
+   */
+  readonly evalSource?: string;
 }
 
 /** A detached Bun CLI child and the common reap ladder used to stop it. */
@@ -32,12 +39,19 @@ export interface CliChild {
  *
  * The returned `stop` closes stdin, then escalates through SIGTERM and group
  * SIGKILL via `reap()`. It never interprets CLI argv, stdout, or fd 3.
+ *
+ * An `evalSource` goes to fd 4 right after the spawn, and that descriptor is
+ * closed at once, because the CLI reads it until end of file (ADR-0033).
  */
 export function startCliChild(options: CliChildOptions): CliChild {
   const child = spawn(options.bun, [options.cli, ...options.argv], {
-    stdio: options.events === true ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
+    stdio: childStdio(options),
     detached: true,
   });
+  if (options.evalSource !== undefined) {
+    const pipe = child.stdio[4];
+    if (isWritable(pipe)) writeEvalSource(pipe, options.evalSource);
+  }
   const stderr = new StderrTail();
   const exited = observeExit(child);
   releasePipesAfterExit(child);
@@ -79,6 +93,22 @@ function isReadable(stream: unknown): stream is Readable {
   return typeof stream === "object" && stream !== null && "on" in stream;
 }
 
+function isWritable(stream: unknown): stream is Writable {
+  return typeof stream === "object" && stream !== null && "end" in stream;
+}
+
+/**
+ * The stdio slots one child needs: the three standard ones, fd 3 for
+ * Lifecycle Events, and fd 4 for the Inline Program source. Fd 4 needs an fd 3
+ * slot, so an `evalSource` always gets the events slot too.
+ */
+function childStdio(options: CliChildOptions): StdioOptions {
+  const stdio: StdioOptions = ["pipe", "pipe", "pipe"];
+  if (options.events === true || options.evalSource !== undefined) stdio.push("pipe");
+  if (options.evalSource !== undefined) stdio.push("pipe");
+  return stdio;
+}
+
 async function text(stream: Readable | null): Promise<string> {
   if (stream === null) return "";
   let out = "";
@@ -114,8 +144,8 @@ const PIPE_EOF_GRACE_MS = 2_000;
 function releasePipesAfterExit(child: ReturnType<typeof spawn>): void {
   child.once("exit", () => {
     const timer = setTimeout(() => {
-      for (const stream of [child.stdout, child.stderr, child.stdio[3]]) {
-        if (isReadable(stream) && !stream.destroyed) stream.destroy();
+      for (const stream of [child.stdout, child.stderr, child.stdio[3], child.stdio[4]]) {
+        if ((isReadable(stream) || isWritable(stream)) && !stream.destroyed) stream.destroy();
       }
     }, PIPE_EOF_GRACE_MS);
     // A housekeeping timer must never keep the host process alive.

package/src/eval-pipe.ts

@@ -0,0 +1,25 @@
+import type { Writable } from "node:stream";
+
+/**
+ * The descriptor an Inline Program's source travels on, never argv (ADR-0033).
+ *
+ * An argv element is readable by every local user through `ps` and
+ * `/proc/<pid>/cmdline`. Descriptor 3 stays exclusive to Run Lifecycle Events
+ * (ADR-0016), so the source goes on descriptor 4.
+ */
+export const EVAL_FD = 4;
+
+/**
+ * Writes the Inline Program source to the descriptor and closes it.
+ *
+ * One write and a close, because the CLI reads the descriptor until end of
+ * file. Never throws: the CLI can exit before it reads — a bad `--resume`
+ * Cassette is refused before the program loads — and that broken pipe is the
+ * child's failure, reported through its exit code and error output.
+ */
+export function writeEvalSource(stream: Writable, source: string): void {
+  stream.on("error", () => {
+    // EPIPE or ERR_STREAM_DESTROYED: the child is gone, and its outcome says why.
+  });
+  stream.end(source);
+}

package/src/event-reader.ts

@@ -1,6 +1,14 @@
 import type { Readable } from "node:stream";
 import type { LifecycleEvent } from "@yaag/runtime";
 
+/**
+ * The descriptor Run Lifecycle Events travel out on (ADR-0006, ADR-0016).
+ *
+ * It stays exclusive to that stream, which is why an Inline Program's source
+ * goes on descriptor 4 instead (`EVAL_FD`, ADR-0033).
+ */
+export const EVENTS_FD = 3;
+
 /**
  * Reads Lifecycle Events from the CLI's dedicated descriptor: one JSON object
  * per line, wrapped in the `{ v: 1, ... }` envelope (ADR-0016).

package/src/fake-extension-ui.ts

@@ -1,8 +1,7 @@
 /**
  * A fully typed `ExtensionUIContext` for the tui-mode test context.
  *
- * `custom`, `notify`, `editor`, `setWidget`, `setStatus`, and a scripted
- * `select` work;
+ * `custom`, `notify`, `setWidget`, `setStatus`, and a scripted `select` work;
  * every other capability throws, so a dependency a view is not supposed to
  * have fails loudly. The
  * class implements the interface, so pi's UI surface is checked at compile
@@ -32,12 +31,6 @@ export interface Notice {
   readonly level: "info" | "warning" | "error";
 }
 
-/** An editor the view opened, with the body it pre-filled. */
-export interface OpenedEditor {
-  readonly title: string;
-  readonly body: string;
-}
-
 /**
  * The fake terminal size a test gives the view. Both fields are optional and
  * default to a 20x100 terminal; no value here can make construction fail.
@@ -52,7 +45,6 @@ export interface FakeExtensionUiOptions {
 /** Runs the factory `ctx.ui.custom()` receives against fake pi services. */
 export class FakeExtensionUi implements ExtensionUIContext {
   readonly notices: Notice[] = [];
-  readonly edits: OpenedEditor[] = [];
   /** The latest frame per widget key; `undefined` means the key was cleared. */
   readonly widgets = new Map<string, string[] | undefined>();
   /** The latest text per footer key; `undefined` means the key was cleared. */
@@ -102,9 +94,11 @@ export class FakeExtensionUi implements ExtensionUIContext {
     this.notices.push({ message, level: type ?? "info" });
   }
 
-  async editor(title: string, prefill?: string): Promise<string | undefined> {
-    this.edits.push({ title, body: prefill ?? "" });
-    return prefill;
+  // A pi dialog clears the editor container, which removes an open non-overlay
+  // `ui.custom` view and stops pi's input loop (ADR-0034). `select` survives
+  // because the Run picker runs before the view opens.
+  async editor(): Promise<string | undefined> {
+    return unavailable("ui.editor");
   }
 
   async select(): Promise<string | undefined> {

package/src/fake-run-start.ts

@@ -0,0 +1,25 @@
+import { initialSummary } from "@yaag/runtime";
+import type { RunHandle, StartRunOptions } from "./spawn-run.ts";
+
+/** A start seam that never spawns: it captures its options and ends the Run at once. */
+export function fakeStart(stdout = "{}"): {
+  readonly start: (options: StartRunOptions) => RunHandle;
+  readonly seen: StartRunOptions[];
+} {
+  const seen: StartRunOptions[] = [];
+  return {
+    seen,
+    start: (options) => {
+      seen.push(options);
+      return {
+        stop: () => {},
+        outcome: Promise.resolve({
+          code: 0,
+          stdout,
+          stderr: "",
+          summary: initialSummary(),
+        }),
+      };
+    },
+  };
+}

package/src/resume-source.ts

@@ -0,0 +1,77 @@
+import { resolve } from "node:path";
+import type { ProgramParams } from "./run-program-param.ts";
+import type { RunRecord } from "./run-record.ts";
+
+/**
+ * Which stored Inline Program source a Checkpoint path resumes.
+ *
+ * A Cassette is never an execution source (ADR-0033): the caller always gives
+ * the program. For a resume of an Inline Program the caller is the extension
+ * itself, which reads the inline launch source back from its own owner-only Run record
+ * and writes it to descriptor 4. The Cassette stays history only, and the
+ * advisory `programSource` comparison of the CLI keeps its meaning, because the
+ * source it sees is byte-identical to the recorded one.
+ */
+
+/** The stored Runs a resume lookup reads; a structural type, so a test needs no store. */
+export interface InlineSourceLookup {
+  /** The Inline Program source whose Run published `artifact`, or null. */
+  inlineSourceFor(artifact: string): Promise<string | null>;
+}
+
+/**
+ * The stored Inline Program source whose Run published `artifact`, or null.
+ *
+ * Pure. A record matches when its launch is inline and its published Checkpoint
+ * or its `record` path resolves to `artifact`. Records arrive oldest first, so
+ * the last match — the newest Run — wins.
+ */
+export function pickInlineResumeSource(
+  records: readonly RunRecord[],
+  artifact: string,
+): string | null {
+  let found: string | null = null;
+  for (const record of records) {
+    const { launch } = record;
+    if (launch.kind !== "inline") continue;
+    const { script, record: recorded } = launch;
+    const published = record.summary.artifact;
+    const matches =
+      (published !== null && published !== undefined && resolve(published) === artifact) ||
+      (recorded !== undefined && resolve(recorded) === artifact);
+    if (matches) found = script;
+  }
+  return found;
+}
+
+/** What the tool says when no record holds the source of the given Checkpoint. */
+export function noStoredSourceMessage(artifact: string): string {
+  return [
+    "yaag_run: give file or script;",
+    `no Run record for the checkpoint ${artifact} holds an Inline Program source,`,
+    "so give script again to resume it.",
+    "The path must be the same path the Run recorded.",
+  ].join(" ");
+}
+
+/**
+ * The program parameters to run, with a stored Inline Program source supplied.
+ *
+ * A call that gives `file` or `script` passes through untouched, so an explicit
+ * program always wins and an invalid shape still fails in `programTarget`. A
+ * call that gives `resume` alone reads the source from the Run records.
+ *
+ * Throws an `Error` whose message begins with `yaag_run:` when no record holds
+ * the source of that Checkpoint.
+ */
+export async function resolveProgramParams(
+  params: ProgramParams,
+  lookup: InlineSourceLookup,
+): Promise<ProgramParams> {
+  if (params.file !== undefined || params.script !== undefined) return params;
+  if (params.resume === undefined) return params;
+  const artifact = resolve(params.resume);
+  const source = await lookup.inlineSourceFor(artifact);
+  if (source === null) throw new Error(noStoredSourceMessage(artifact));
+  return { ...params, script: source };
+}

package/src/run-argv.ts

@@ -0,0 +1,39 @@
+import { EVAL_FD } from "./eval-pipe.ts";
+import { EVENTS_FD } from "./event-reader.ts";
+
+/** What a Run runs: a program file, or Inline Program source text (ADR-0033). */
+export type ProgramTarget =
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "inline"; readonly source: string };
+
+/** The parts of a Run the CLI argv carries. */
+export interface RunArgvOptions {
+  readonly program: ProgramTarget;
+  /** Opaque JSON, forwarded untouched: the program validates it (ADR-0010). */
+  readonly args?: string;
+  /** Cassette path to write, forwarded as `--record` (ADR-0013). */
+  readonly record?: string;
+  /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
+  readonly resume?: string;
+}
+
+/**
+ * Builds the CLI argv for one Run.
+ *
+ * An Inline Program's source never travels in argv, because argv is readable
+ * by every local user through `ps` and `/proc/<pid>/cmdline`. The argv names
+ * the descriptor only, as `--eval-fd 4` (ADR-0033); the caller writes the
+ * source to that descriptor with `writeEvalSource`. The CLI owns the closed
+ * import contract, and the size guard is upstream in `run-program-param.ts`.
+ */
+export function runArgv(options: RunArgvOptions): readonly string[] {
+  const { program } = options;
+  return [
+    ...(program.kind === "file" ? ["run", program.file] : ["run", "--eval-fd", String(EVAL_FD)]),
+    "--events-fd",
+    String(EVENTS_FD),
+    ...(options.args === undefined ? [] : ["--args", options.args]),
+    ...(options.record === undefined ? [] : ["--record", options.record]),
+    ...(options.resume === undefined ? [] : ["--resume", options.resume]),
+  ];
+}

package/src/run-call-render.ts

@@ -0,0 +1,58 @@
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { fakeTheme } from "./fake-theme.ts";
+import { resolveBun } from "./resolve-bun.ts";
+import { resolveCliEntry } from "./resolve-cli.ts";
+import { RunRegistry } from "./run-registry.ts";
+import { createRunTool } from "./run-tool.ts";
+
+const cli = resolveCliEntry();
+const bun = await resolveBun();
+if (bun === null) throw new Error("these tests need bun on PATH");
+
+/** The `yaag_run` parameters a test gives the tool. */
+export interface RunParams {
+  readonly file?: string;
+  readonly script?: string;
+  readonly args?: string;
+  readonly background?: boolean;
+  readonly record?: string;
+  readonly resume?: string;
+}
+
+function renderCallComponent(params: RunParams, expanded: boolean) {
+  const tool = createRunTool({
+    bun,
+    cli,
+    registry: new RunRegistry(),
+    sendMessage: () => undefined,
+  });
+  const component = tool.renderCall?.(params, fakeTheme(), {
+    args: params,
+    toolCallId: "call-1",
+    invalidate: () => {},
+    lastComponent: undefined,
+    state: undefined,
+    cwd: process.cwd(),
+    executionStarted: false,
+    argsComplete: true,
+    isPartial: false,
+    expanded,
+    showImages: false,
+    isError: false,
+  });
+  return component;
+}
+
+/** The call line, stripped of styling, as the collapsed transcript shows it. */
+export function renderCallLabel(params: RunParams): string {
+  return stripTerminalSequences(renderCallComponent(params, false)?.render(80)[0] ?? "");
+}
+
+/** Every rendered line of the call, stripped of styling. */
+export function renderCallLines(
+  params: RunParams,
+  options: { readonly expanded?: boolean } = {},
+): readonly string[] {
+  const component = renderCallComponent(params, options.expanded ?? false);
+  return (component?.render(80) ?? []).map(stripTerminalSequences);
+}

package/src/run-program-param.ts

@@ -0,0 +1,178 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { clampToWidth, sanitizeTerminalLine, sanitizeTerminalText } from "@yaag/tui";
+import type { ProgramTarget } from "./run-argv.ts";
+
+/**
+ * The `yaag_run` parameters that name the program; exactly one is given.
+ *
+ * `resume` names a Checkpoint. It is read at render time only: a call that
+ * gives `resume` alone takes its source from the Run record (`resume-source.ts`).
+ */
+export interface ProgramParams {
+  readonly file?: string;
+  readonly script?: string;
+  readonly resume?: string;
+}
+
+/** The expanded view keeps at most this many source lines. */
+const EXPANSION_LINES = 200;
+/** The expanded view keeps at most this many source bytes. */
+const EXPANSION_BYTES = 8192;
+
+/**
+ * The largest Inline Program the tool accepts, in UTF-8 bytes.
+ *
+ * The source travels on descriptor 4, and never in argv (ADR-0033), so the
+ * MAX_ARG_STRLEN limit of Linux no longer applies. The cap now bounds the
+ * volume the transcript and the durable Run record hold — `run-record.ts`
+ * keeps the whole `script` — and keeps the write to the descriptor bounded.
+ * It refuses early, with a message that says what to do.
+ */
+export const MAX_SCRIPT_BYTES = 65_536;
+
+/**
+ * The widest a rendered call label may be, in terminal display columns.
+ *
+ * A path is caller-controlled and unbounded; the call line must stay one
+ * readable line on a narrow terminal. Columns, not UTF-16 units: 60 CJK
+ * characters occupy 120 columns.
+ */
+export const LABEL_WIDTH = 60;
+
+/**
+ * Validates the shape of the program parameters and names the target.
+ *
+ * Pure: it touches no filesystem, so a Host Session with no Bun still gets the
+ * Bun status report rather than a path error (ADR-0033). A `file` target is
+ * resolved to an absolute path but never probed — that is
+ * {@link confirmProgramTarget}.
+ *
+ * Throws an `Error` whose message begins with `yaag_run:` when the parameters
+ * are not one program: both `file` and `script`, neither of them, a `script`
+ * that is blank, or a `script` above {@link MAX_SCRIPT_BYTES} bytes.
+ */
+export function programTarget(params: ProgramParams): ProgramTarget {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) {
+    throw new Error("yaag_run: give file or script, and not both");
+  }
+  if (script !== undefined) {
+    if (script.trim() === "") throw new Error("yaag_run: script is empty");
+    const bytes = byteCount(script);
+    if (bytes > MAX_SCRIPT_BYTES) {
+      throw new Error(
+        `yaag_run: script is too large (${bytes} bytes); write it to a file and use file`,
+      );
+    }
+    return { kind: "inline", source: script };
+  }
+  if (file === undefined) throw new Error("yaag_run: give file or script");
+  return { kind: "file", file: resolve(file) };
+}
+
+/**
+ * Confirms a file target exists; an Inline Program passes through untouched.
+ *
+ * Rejects with `yaag_run: no such Orchestration Program: <path>` when the file
+ * is not accessible. An inline target never touches the filesystem.
+ */
+export async function confirmProgramTarget(target: ProgramTarget): Promise<ProgramTarget> {
+  if (target.kind === "inline") return target;
+  try {
+    await access(target.file);
+  } catch {
+    throw new Error(`yaag_run: no such Orchestration Program: ${target.file}`);
+  }
+  return target;
+}
+
+/**
+ * A one-line label for the call render. Total by design: the render runs before
+ * `execute` validates, so an invalid parameter pair must still produce a label.
+ *
+ * The label never quotes the source. `yaag_run` has no approval gate, so any
+ * text taken from an Inline Program would be a trust-bearing string the model
+ * chose — a comment or an unrelated `name:` could name a program that is not
+ * the one that runs. The Inline Program branch states only what the extension
+ * measured: its kind and its size in bytes. The source itself is shown, whole,
+ * in the expanded view ({@link programExpansion}).
+ *
+ * The two caller-controlled branches — a file path and a Checkpoint path — are
+ * sanitized to one line and clamped to {@link LABEL_WIDTH} columns, so a
+ * hostile path can neither emit an escape byte nor overflow the call line. The
+ * clamp covers the whole `Inline Program from …` text, prefix included.
+ */
+export function programLabel(params: ProgramParams): string {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) return "(invalid call)";
+  if (script !== undefined) {
+    if (script.trim() === "") return "(empty script)";
+    const bytes = byteCount(script);
+    return `Inline Program, ${bytes} ${bytes === 1 ? "byte" : "bytes"}`;
+  }
+  if (file !== undefined) return safeLabel(file);
+  // A resume with no file and no script is a valid call: the source comes from
+  // the Run record, and the label names the Checkpoint the source belongs to.
+  if (params.resume !== undefined) return safeLabel(`Inline Program from ${params.resume}`);
+  return "(invalid call)";
+}
+
+function safeLabel(value: string): string {
+  return clampToWidth(sanitizeTerminalLine(value), LABEL_WIDTH);
+}
+
+/**
+ * The Inline Program source as the expanded call view shows it: sanitized,
+ * verbatim, and capped so a huge script cannot flood the transcript.
+ *
+ * Returns an empty string when the call names a file or is invalid, and for a
+ * resume of a stored Inline Program: the source is not known at render time.
+ * This cap
+ * bounds transcript volume only; the transport cap is {@link MAX_SCRIPT_BYTES}.
+ */
+export function programExpansion(params: ProgramParams): string {
+  const { file, script } = params;
+  if (file !== undefined || script === undefined || script.trim() === "") return "";
+  const total = byteCount(script);
+  const source = sanitizeTerminalText(script).replace(/\n+$/, "");
+  const lines: string[] = [];
+  let kept = 0;
+  let cut = false;
+  for (const line of source.split("\n")) {
+    if (lines.length >= EXPANSION_LINES) {
+      cut = true;
+      break;
+    }
+    if (kept + byteCount(line) > EXPANSION_BYTES) {
+      // A minified program can be one line longer than the whole cap. Keep the
+      // prefix that fits, so the view still shows where the source starts.
+      const head = bytePrefix(line, EXPANSION_BYTES - kept);
+      if (head !== "") lines.push(`  ${head}`);
+      cut = true;
+      break;
+    }
+    kept += byteCount(line) + 1;
+    lines.push(`  ${line}`);
+  }
+  if (cut) lines.push(`  … (truncated, ${total} bytes total)`);
+  return lines.join("\n");
+}
+
+function byteCount(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+/** The longest prefix of `value` that fits `limit` UTF-8 bytes, whole characters only. */
+function bytePrefix(value: string, limit: number): string {
+  if (limit <= 0) return "";
+  let kept = "";
+  let used = 0;
+  for (const character of value) {
+    const size = byteCount(character);
+    if (used + size > limit) break;
+    used += size;
+    kept += character;
+  }
+  return kept;
+}