@teaflask/assistant 0.0.0 → 0.3.0

package/src/transcript-ui.ts

@@ -0,0 +1,78 @@
+// The transcript surface: the React component over the
+// ./transcript projection layer — one component, three binders (the
+// package's own Transcript, the dashboard's agent-run viewer, the
+// playground). This entry is deliberately separate from ./transcript,
+// which is React-free by construction; a host that only projects rows
+// never pays for React, and a host that mounts the surface imports it
+// from here. Like every entry: additions are cheap until the package
+// publishes, breaking changes are a customer conversation after.
+
+export {
+  AssistantTranscript,
+  type AssistantTranscriptProps,
+  type AgentTranscriptSource,
+  type RowsTranscriptSource,
+} from "./components/assistant-transcript.js";
+
+// The slot contracts.
+export type {
+  MessageViewSlot,
+  ToolRowSlot,
+  ToolRowSlotProps,
+  TranscriptMarkerProps,
+  TranscriptSlotRow,
+} from "./components/message-list.js";
+
+// The shapes a binder types its own props and fills against.
+export type {
+  MarkerBoundaries,
+  MarkerPosition,
+  ToolCallRow,
+  TranscriptRow,
+  UserMessageRow,
+  AssistantTextRow,
+  SubagentDeliveryRow,
+} from "./core/transcript-rows.js";
+export type { ToolCallState } from "./core/tool-call-display.js";
+export type { SubagentGroupRow } from "./core/subagent-rows.js";
+export type { ToolCallViewModel } from "./core/tool-call-display.js";
+export type { ApprovalCardModel } from "./core/approval-inbox.js";
+export type { TurnAttachment } from "./contract/threads.js";
+
+// The decision surfaces, unforked: the approval banner and the
+// question panel, with the contexts a host provides them through — the
+// cards travel by context because the composer block and the transcript
+// both read them. The playground's forked copies were deleted; these are
+// the one rendered home of each.
+export { ApprovalCard } from "./components/approval-card.js";
+export {
+  ApprovalsContext,
+  type ApprovalSurface,
+} from "./components/approval-context.js";
+export { QuestionPanel } from "./components/question-panel.js";
+export {
+  ElicitationsContext,
+  type ElicitationSurface,
+} from "./components/elicitation-context.js";
+
+// The pending-decision gap's one rendered spelling: the playground's
+// composer renders this rather than transcribing the copy — the
+// sentence lives only in notice-banner.tsx.
+// Consumer: the dashboard's playground-composer.tsx.
+export { PendingDecisionGapNotice } from "./components/notice-banner.js";
+
+// The agent identity mark, unforked: the dashboard's copy was
+// a cn/cx rename away from this one and is now a re-export shim; the
+// parity suite pins the logo geometry against this component directly.
+export {
+  AgentIdentityMark,
+  type AgentIdentityRegister,
+} from "./components/agent-identity-mark.js";
+
+// The one subscribe-for-a-lifetime hook: every recorder
+// component that used to hand-roll useEffect + agent.subscribe +
+// unsubscribe mounts its subscriber through this instead — the dashboard's
+// marker recorders, inbox recorders and stream taps included, so the
+// idiom exists once. Consumers: components/agent-run/*, agents/playground/*,
+// and the conversations tree through agent-run/roster.ts.
+export { useAgentSubscriber } from "./components/use-agent-subscriber.js";

package/src/transcript.ts

@@ -0,0 +1,277 @@
+// The transcript projection layer, shared with the dashboard's agent-run
+// viewer: the row derivation, the anchor recorders and the
+// subagent grouping exist once, here. Wire-agnostic, React-free and
+// transport-free by construction — MarkerAnchorsSnapshot rides type-only
+// so connection-epoch's transport never enters this closure. AG-UI names
+// are re-exported so a host never depends on the @ag-ui packages itself.
+
+// The chassis seam.
+export { AbstractAgent, HttpAgent } from "@ag-ui/client";
+export type { AgentSubscriber } from "@ag-ui/client";
+export type { BaseEvent, Message, RunAgentInput } from "@ag-ui/core";
+
+// The tool-outcome lift a host's own HttpAgent subclass pipes its run()
+// through, and the reader the anchor families use — the wire's five
+// TOOL_CALL_RESULT extras survive the 1.0 client's enforcement only under
+// event metadata.
+export {
+  liftToolOutcome,
+  toolOutcomeOf,
+  withToolOutcomeLifted,
+  type ToolOutcome,
+} from "./core/tool-outcome.js";
+
+// The flat row projection. Scope note: MarkerAnchorsSnapshot has
+// fifteen anchor fields and this entry ships recorders for seven
+// (display, error, cancel, refusal, decision, denial — the last two optional
+// on the snapshot, absent reading as empty — and the string-receipt family).
+// The other eight are passable empty but not populatable from here: a
+// live-store host populates every anchor itself; only an own-wire host
+// composing its own snapshot waits. The counts are executed, not trusted
+// (tests/tool-call-state-sites.test.ts; approvalInboxRecorder feeds no
+// snapshot field, so it sits outside them).
+export {
+  errorTextOf,
+  transcriptRowsOf,
+  type TranscriptRow,
+} from "./core/transcript-rows.js";
+export type { MarkerAnchorsSnapshot } from "./core/connection-epoch.js";
+
+// The wire taps.
+export { messagesRecorder, streamErrorRecorder } from "./core/messages-cell.js";
+
+// The tool-call anchor families: for each, the empty constant, the
+// idempotent merge and the recorder — the surface a composition wires.
+export type { ToolCallDisplay } from "./core/tool-call-display.js";
+export {
+  EMPTY_TOOL_CALL_DISPLAY_ANCHORS,
+  toolCallDisplayRecorder,
+  withToolCallDisplayAnchored,
+} from "./core/tool-call-display-anchors.js";
+export {
+  EMPTY_TOOL_ERROR_ANCHORS,
+  toolErrorRecorder,
+  withToolErrorAnchored,
+} from "./core/tool-error-anchors.js";
+export {
+  EMPTY_TOOL_CANCEL_ANCHORS,
+  toolCancelRecorder,
+  withToolCancelAnchored,
+} from "./core/tool-cancel-anchors.js";
+export {
+  EMPTY_TOOL_REFUSAL_ANCHORS,
+  toolRefusalRecorder,
+  withToolRefusalAnchored,
+} from "./core/tool-refusal-anchors.js";
+export {
+  EMPTY_TOOL_DECISION_ANCHORS,
+  toolDecisionRecorder,
+  withToolDecisionAnchored,
+} from "./core/tool-decision-anchors.js";
+// The denial family ships a LEDGER, not a set: the recorder's
+// marker is folded into the same value on every host, and the snapshot
+// takes the ledger's `denied` half. Without this trio a composer over
+// transcriptRowsOf would hold a ladder rung no exported recorder can
+// populate — and render every member denial as Interrupted.
+export {
+  EMPTY_TOOL_DENIAL_LEDGER,
+  toolDenialRecorder,
+  withToolDenialMarkerFolded,
+  type ToolDenialLedger,
+  type ToolDenialMarker,
+} from "./core/tool-denial-anchors.js";
+// The string-receipt family: the dashboard's run viewer and
+// playground bind their turn_failed and turn_stopped rows to it by event
+// name; the recorder feeds the snapshot's turnFailedAnchors field.
+export {
+  receiptMarkerRecorder,
+  receiptOf,
+  withReceiptAnchored,
+  type AnchoredReceipts,
+} from "./core/receipt-anchors.js";
+export {
+  EMPTY_TURN_FAILED_ANCHORS,
+  turnFailedReceiptOf,
+  withTurnFailedAnchored,
+  type AnchoredTurnFailReceipts,
+} from "./core/turn-failed-anchors.js";
+
+// The subagent surfaces.
+export {
+  rosterEntriesOf,
+  settledDurationLabelOf,
+  subagentPillLabelOf,
+  subagentRosterOf,
+  type RosterSourceDispatch,
+  type RosterStatusPredicates,
+  type SubagentRoster,
+  type SubagentRosterEntry,
+} from "./core/subagent-roster.js";
+export {
+  DISPATCH_SUBAGENT_TOOL_NAME,
+  dispatchReceiptOf,
+  subagentGroupHeadlineOf,
+  subagentOutcomeCountsOf,
+  taskExcerptOf,
+  withSubagentGroups,
+  type DispatchCall,
+  type DispatchReceipt,
+  type SubagentGroupEntry,
+  type SubagentGroupRow,
+  type SubagentOutcomeCounts,
+} from "./core/subagent-rows.js";
+export { coworkerIndicesOf } from "./core/subagent-presence.js";
+
+// The elicitation narrowing.
+export {
+  askQuestionsActionOf,
+  type QuestionModel,
+} from "./core/elicitation-pickers.js";
+
+// The approval inbox: the React-free state machine behind the
+// approval banner and the recorder that feeds it. A host constructs one per
+// conversation, subscribes the recorder, renders ApprovalCard, and — if its
+// door serves a turn record — re-judges on every REST read against the
+// lenient ApprovalTurnRecord (every pause field optional: degrade, never
+// demand). The three stamped flags are opt-in capabilities, default off.
+export {
+  ANSWER_NOT_SENT_SENTENCE,
+  ApprovalInbox,
+  approvalInboxRecorder,
+  answerablePauseOf,
+  reconcileApprovalsWithTurns,
+  SERVING_APPROVAL_CAPABILITIES,
+  type ApprovalCardModel,
+  type ApprovalCardStatus,
+  type ApprovalDecisionInput,
+  type ApprovalInboxCapabilities,
+  type ApprovalTurnRecord,
+} from "./core/approval-inbox.js";
+
+// The one definition of "this decision still waits on the member" for each
+// card family: hosts read these rather than respelling the status
+// arithmetic, so a status the package adds later is judged in one place.
+export {
+  approvalAwaitsMember,
+  elicitationAwaitsMember,
+} from "./core/suspension-queue.js";
+
+// The question-set drafts and the card shapes the question panel reads:
+// the draft store is import-free and lives above the transcript's
+// remount key in every host; the card types let a React-free host build them.
+export { QuestionDraftStore } from "./core/question-drafts.js";
+export type {
+  AnsweredQuestions,
+  ElicitationCardModel,
+  ElicitationCardStatus,
+  QuestionSetCardModel,
+} from "./core/elicitation-cards.js";
+
+// The execution vocabulary a refusing surface needs: the canned
+// refusal (the contract's documented degrade for kinds a client can't
+// execute), the member-answerable set and the ask kind, so a host gates on
+// the PACKAGE's vocabulary and never auto-answers a kind whose executor is
+// the member. All from the dependency-free kinds leaf; the closure holds.
+export {
+  ASK_QUESTIONS_REQUEST_KIND,
+  KIND_UNSUPPORTED_OUTCOME,
+  MEMBER_ANSWERABLE_KINDS,
+} from "./core/execution-kinds.js";
+
+// The execution wire's two CUSTOM marker names: a host recorder
+// feeding its own inbox matches the same names the package's recorders do,
+// so the wire vocabulary stays single-sourced.
+export {
+  TOOL_EXECUTION_REQUESTED_EVENT_NAME,
+  TOOL_RESULT_RECORDED_EVENT_NAME,
+} from "./contract/events.js";
+// The marker names the dashboard's own receipt and divider rows narrow,
+// imported here so the wire vocabulary stays single-sourced
+// rather than respelled from the generated enum beside each row.
+export {
+  APPROVAL_RESOLVED_EVENT_NAME,
+  RUN_RESUMED_EVENT_NAME,
+  SUBAGENT_RESULTS_DELIVERED_EVENT_NAME,
+  TURN_FAILED_EVENT_NAME,
+  TURN_STOPPED_EVENT_NAME,
+} from "./contract/events.js";
+// The delivery marker's narrower and shape: the dashboard's
+// delivery divider imports the package's narrowing; only its label is its own.
+export {
+  deliveredResultsOf,
+  type DeliveredResult,
+} from "./core/subagent-delivery-anchors.js";
+// The approval_resolved narrower: carries the two optional
+// fields the dashboard's audit receipt row renders, and exists once.
+export {
+  approvalResolvedPayloadOf,
+  type ApprovalResolved,
+} from "./core/approval-resolved.js";
+// The execution driver's delivery cap: one value, one leaf.
+export { MAX_DELIVERY_ATTEMPTS } from "./core/execution-kinds.js";
+// A coworker's execution request as the turn snapshot lists it:
+// the dashboard's playground refuses it through the same
+// narrowing the package's driver executes it with.
+export {
+  coworkerExecutionRequestOf,
+  type CoworkerExecutionRequest,
+} from "./core/execution-request-narrowing.js";
+
+// The pending-decision gap: the playground's decision surface
+// computes the same "a pending interrupt id nothing client-side answers
+// for" verdict the widget store publishes — one derivation AND one
+// quiet→loud grace, never a twin. The leaf's only import is a type, so this
+// entry's transport-free closure holds. GapJudgeableTurn is deliberately
+// NOT here: callers pass their own turn types structurally (no consumer).
+export {
+  GAP_PROBE_SETTLE_MS,
+  PendingDecisionGapGate,
+  pendingDecisionGapOf,
+  type PendingDecisionGap,
+} from "./core/pending-decision-gap.js";
+
+// The conversation core's timing and paging policies, single-sourced: the
+// settle re-read's debounce, the stop's bounded fallback probe, and the
+// turns cursor walk. Their constants stay module-level — the policies carry
+// them and nothing dashboard-side names them (the no-consumer rule). All
+// three are setTimeout-only leaves, so the transport-free closure holds.
+export { SettleRefreshScheduler } from "./core/settle-refresh.js";
+export { probeStopSettle } from "./core/stop-settle.js";
+export { backfilledTurnsOf } from "./core/turns-backfill.js";
+
+// The user-turn ledger's injector and id derivation: the
+// injector is generic over the InjectableTurnLedger slice both the package
+// and dashboard ledgers satisfy, so it exists once.
+export { userMessageIdFor, userTurnInjector } from "./core/user-turn-ledger.js";
+
+// The composer policy leaf: the per-message bounds, the cap
+// accounting, the pick-time size cap and the Escape/Enter verbs both
+// composers apply — the package slab's and the dashboard playground's.
+export {
+  attachmentDraftFailed,
+  capSlotsSpentBy,
+  CHARACTER_COUNT_VISIBLE_FROM,
+  composerKeyHandlersOf,
+  mintAttachmentDraftId,
+  pickCapOf,
+  type AttachmentDraft,
+} from "./core/composer-policy.js";
+export {
+  ASSISTANT_MAX_ATTACHMENTS,
+  ASSISTANT_MESSAGE_MAX_CHARS,
+} from "./contract/threads.js";
+// The stop door's generic failure line: one leaf, no respelling.
+export { STOP_NOT_DELIVERED_SENTENCE } from "./core/stop-copy.js";
+
+// The subscriber off switch: a recorder that connectAgent has
+// snapshotted into a run outliving its effect is silenced by dispose(),
+// not by the unsubscribe that cannot reach that run.
+export {
+  disposableSubscriber,
+  type DisposableAgentSubscriber,
+} from "./core/disposable-subscriber.js";
+
+// Presentation leaves.
+export { newestAssistantProseIdOf } from "./core/assistant-prose.js";
+export { prettyPrintParameters } from "./components/pretty-print.js";
+export { humanFileSize } from "./components/human-file-size.js";

package/src/transport/actions-adapter.ts

@@ -0,0 +1,227 @@
+// How one server-built http_intent becomes a real HTTP request through
+// the host's actions adapter — transport, so it may hold this package's
+// fetch. React-free on purpose: the narrowing, URL assembly, and result
+// synthesis are the risky parts, and they unit-test in node. Whatever
+// the adapter kind, the package itself synthesizes the contract's strict
+// HttpIntentResult — a host can never malform the wire shape into a 422.
+
+import type {
+  ActionIntent,
+  ActionsAdapter,
+  CookiesActionsAdapter,
+  HeadersActionsAdapter,
+} from "../contract/actions-adapter.js";
+import type { HttpIntentResult } from "../generated/models/index.js";
+import {
+  boundedTextOf,
+  doorCostOfText,
+  doorLengthCeilingOf,
+} from "./door-budget.js";
+
+// The body bound is a ceiling of the tool-results door's own serialized
+// metric (see door-budget.ts), sized to leave headroom for the result's
+// sibling fields under the door's 20k cap.
+const RESPONSE_BODY_MAX_CHARS = 16_000;
+// The visible cut marker (the read_page posture): the model reads the
+// truncation in the text, and the wire's truncated flag says it too.
+const TRUNCATION_NOTICE =
+  "… [truncated: the response was larger than fits here]";
+
+/**
+ * Narrow the wire's snake_case intent payload into the frozen camelCase
+ * ActionIntent. The server built it from the vetted catalog row, so this
+ * is only wire defense: any malformed shape answers null and the caller
+ * reports the canned unusable-intent error without touching the adapter.
+ */
+export function actionIntentOf(
+  wire: Record<string, unknown> | null,
+): ActionIntent | null {
+  if (wire === null) {
+    return null;
+  }
+  const action = _actionIdentityOf(wire.action);
+  const method = _nonEmptyStringOf(wire.method);
+  const pathTemplate = _nonEmptyStringOf(wire.path_template);
+  const pathParams = _recordOf(wire.path_params);
+  const query = _recordOf(wire.query);
+  if (
+    action === null ||
+    method === null ||
+    pathTemplate === null ||
+    pathParams === null ||
+    query === null
+  ) {
+    return null;
+  }
+  const intent: ActionIntent = {
+    action,
+    method,
+    pathTemplate,
+    pathParams,
+    query,
+  };
+  if (wire.body !== null && wire.body !== undefined) {
+    intent.body = wire.body;
+  }
+  return intent;
+}
+
+/** Execute one intent through whichever adapter the host wired. */
+export async function performActionIntent(
+  adapter: ActionsAdapter,
+  intent: ActionIntent,
+): Promise<HttpIntentResult> {
+  if (adapter.kind === "request") {
+    // The host's wrapper owns transport: a resolved value is the API's
+    // response body, a rejection propagates as a failed execution.
+    return _intentResultOf(200, await adapter.execute(intent));
+  }
+  const response = await fetch(
+    _urlOf(adapter.baseUrl, intent),
+    await _requestInitOf(adapter, intent),
+  );
+  return _resultOf(response);
+}
+
+function _intentResultOf(status: number, rawBody: unknown): HttpIntentResult {
+  const landed = _landableBodyOf(rawBody);
+  return { status, body: landed.body, truncated: landed.truncated };
+}
+
+function _landableBodyOf(body: unknown): { body: unknown; truncated: boolean } {
+  // The wire's body field is required, so a wrapper that resolves nothing
+  // (a 204-style empty answer) still has to land; an unserializable value
+  // has no wire form at all. (The TS lib types stringify as
+  // always-string; it answers undefined for undefined/function/symbol.)
+  if (body === undefined) {
+    return { body: null, truncated: false };
+  }
+  const serialized = JSON.stringify(body) as string | undefined;
+  if (serialized === undefined) {
+    return { body: null, truncated: false };
+  }
+  if (doorLengthCeilingOf(serialized) <= RESPONSE_BODY_MAX_CHARS) {
+    return { body, truncated: false };
+  }
+  // Too big for the door: degrade to a bounded string — the raw text for
+  // a string body, the JSON text for a structured one — truncated by its
+  // own escaped footprint so the degraded delivery is landable too, with
+  // the visible marker so the cut is never mistaken for the whole.
+  const bounded = boundedTextOf(
+    typeof body === "string" ? body : serialized,
+    RESPONSE_BODY_MAX_CHARS - doorCostOfText(TRUNCATION_NOTICE),
+  );
+  return { body: bounded + TRUNCATION_NOTICE, truncated: true };
+}
+
+async function _requestInitOf(
+  adapter: CookiesActionsAdapter | HeadersActionsAdapter,
+  intent: ActionIntent,
+): Promise<RequestInit> {
+  const headers: Record<string, string> = {};
+  if (intent.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (adapter.kind === "headers") {
+    // The host's headers land last so they win any collision.
+    Object.assign(headers, await adapter.getHeaders(intent));
+  }
+  return {
+    method: intent.method,
+    headers,
+    ...(adapter.kind === "cookies" ? { credentials: "include" as const } : {}),
+    ...(intent.body !== undefined ? { body: JSON.stringify(intent.body) } : {}),
+  };
+}
+
+function _urlOf(baseUrl: string, intent: ActionIntent): string {
+  return (
+    _withoutTrailingSlash(baseUrl) +
+    _substitutedPathOf(intent) +
+    _queryStringOf(intent.query)
+  );
+}
+
+function _withoutTrailingSlash(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+function _substitutedPathOf(intent: ActionIntent): string {
+  return intent.pathTemplate.replace(
+    /\{(\w+)\}/g,
+    (_placeholder, name: string) => {
+      const value = intent.pathParams[name];
+      if (value === undefined) {
+        throw new Error(
+          `The intent's path names a {${name}} parameter it did not supply.`,
+        );
+      }
+      return encodeURIComponent(_parameterTextOf(value));
+    },
+  );
+}
+
+function _parameterTextOf(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  // The server validated the params against the action's own schemas, so
+  // a composite value's JSON text is the honest encoding — never the
+  // default "[object Object]".
+  return JSON.stringify(value);
+}
+
+function _queryStringOf(query: Record<string, unknown>): string {
+  const parameters = new URLSearchParams();
+  for (const [name, value] of Object.entries(query)) {
+    if (value !== null && value !== undefined) {
+      parameters.append(name, _parameterTextOf(value));
+    }
+  }
+  const encoded = parameters.toString();
+  return encoded === "" ? "" : `?${encoded}`;
+}
+
+async function _resultOf(response: Response): Promise<HttpIntentResult> {
+  // A non-2xx status is a result, never a failure: the assistant
+  // confirms or explains from the API's real answer. Only transport
+  // trouble (fetch throwing) reads as a failed execution.
+  return _intentResultOf(response.status, _jsonOrTextOf(await response.text()));
+}
+
+function _jsonOrTextOf(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function _actionIdentityOf(
+  value: unknown,
+): { slug: string; title: string } | null {
+  const record = _recordOf(value);
+  if (record === null) {
+    return null;
+  }
+  const slug = _nonEmptyStringOf(record.slug);
+  const title = _nonEmptyStringOf(record.title);
+  if (slug === null || title === null) {
+    return null;
+  }
+  return { slug, title };
+}
+
+function _nonEmptyStringOf(value: unknown): string | null {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+function _recordOf(value: unknown): Record<string, unknown> | null {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}

package/src/transport/door-budget.ts

@@ -0,0 +1,78 @@
+// The tool-results door refuses results whose serialized JSON passes 20k
+// chars — measured server-side with ensure_ascii escaping and spaced
+// separators — and a refused POST would strand the turn until it parks.
+// Every client-side size bound on a deliverable payload must therefore be
+// taken against a CEILING of the door's own metric, never against raw JS
+// string length: non-ASCII re-escapes into 6-char \uXXXX sequences and a
+// truncated-text payload re-escapes its quotes, either of which can
+// inflate a "small" payload past the cap. Shared by whichever producer
+// ships text through the door (action responses, page reads).
+
+/**
+ * A ceiling on the length the tool-results door will measure for a
+ * client-serialized JSON text: the door re-serializes with ensure_ascii
+ * (every non-ASCII UTF-16 unit becomes a 6-char \uXXXX) and spaced
+ * separators (every comma and colon may gain a space). In-string commas
+ * are over-counted — a ceiling never needs to be exact, only never under.
+ */
+export function doorLengthCeilingOf(serialized: string): number {
+  let length = 0;
+  for (let index = 0; index < serialized.length; index += 1) {
+    const code = serialized.charCodeAt(index);
+    if (code > 0x7f) {
+      length += 6;
+    } else if (code === 0x2c /* , */ || code === 0x3a /* : */) {
+      length += 2;
+    } else {
+      length += 1;
+    }
+  }
+  return length;
+}
+
+/**
+ * Truncate by what each unit will cost once this text rides as a JSON
+ * string through the door's ensure_ascii serializer, at worst case — a
+ * raw-length cut could still blow the cap on re-escaping. Never splits a
+ * surrogate pair.
+ */
+export function boundedTextOf(text: string, maxEscapedChars: number): string {
+  let budget = maxEscapedChars;
+  let end = 0;
+  while (end < text.length) {
+    const cost = escapedCostOf(text.charCodeAt(end));
+    if (cost > budget) {
+      break;
+    }
+    budget -= cost;
+    end += 1;
+  }
+  if (end > 0 && _isHighSurrogate(text.charCodeAt(end - 1))) {
+    end -= 1; // never cut a surrogate pair in half
+  }
+  return text.slice(0, end);
+}
+
+/** The worst-case door footprint of a whole text inside a JSON string. */
+export function doorCostOfText(text: string): number {
+  let cost = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    cost += escapedCostOf(text.charCodeAt(index));
+  }
+  return cost;
+}
+
+/** The worst-case door footprint of one UTF-16 unit inside a JSON string. */
+export function escapedCostOf(code: number): number {
+  if (code > 0x7f || code < 0x20) {
+    return 6;
+  }
+  if (code === 0x22 /* " */ || code === 0x5c /* \ */) {
+    return 2;
+  }
+  return 1;
+}
+
+function _isHighSurrogate(code: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff;
+}