Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

packages/tool-call-repair/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@openclaw/tool-call-repair",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

packages/tool-call-repair/src/grammar.ts

@@ -0,0 +1,236 @@
+/** Legacy marker some models emit after a serialized JSON tool request. */
+export const END_TOOL_REQUEST = "[END_TOOL_REQUEST]";
+/** Harmony stream marker that introduces the target channel before a tool call. */
+export const HARMONY_CHANNEL_MARKER = "<|channel|>";
+/** Harmony stream marker that may separate the header from the JSON payload. */
+export const HARMONY_MESSAGE_MARKER = "<|message|>";
+/** Harmony stream marker that may close a serialized tool-call payload. */
+export const HARMONY_CALL_MARKER = "<|call|>";
+
+/** Accepts either a complete literal or a still-streaming prefix of that literal. */
+export function matchesLiteralPrefix(text: string, literal: string): boolean {
+  return literal.startsWith(text) || text.startsWith(literal);
+}
+
+/** Tool names in bracket/plain-text repairs intentionally match provider-safe ids only. */
+export function isPlainTextToolNameChar(char: string | undefined): boolean {
+  return Boolean(char && /[A-Za-z0-9_-]/.test(char));
+}
+
+/** XML-ish function tags allow namespace punctuation used by some model families. */
+export function isXmlishNameChar(char: string | undefined): boolean {
+  return Boolean(char && /[A-Za-z0-9_.:-]/.test(char));
+}
+
+/** Skips spaces and tabs only, preserving line boundaries for grammar decisions. */
+export function skipHorizontalWhitespace(text: string, start: number): number {
+  let index = start;
+  while (index < text.length && (text[index] === " " || text[index] === "\t")) {
+    index += 1;
+  }
+  return index;
+}
+
+/** Skips all JavaScript whitespace when line structure is no longer meaningful. */
+export function skipWhitespace(text: string, start: number): number {
+  let index = start;
+  while (index < text.length && /\s/.test(text[index] ?? "")) {
+    index += 1;
+  }
+  return index;
+}
+
+/** Consumes either Unix or Windows line endings and returns the first offset after them. */
+export function consumeLineBreak(text: string, start: number): number | null {
+  if (text[start] === "\r") {
+    return text[start + 1] === "\n" ? start + 2 : start + 1;
+  }
+  if (text[start] === "\n") {
+    return start + 1;
+  }
+  return null;
+}
+
+/** Finds the exclusive end offset of a balanced JSON object starting at `start`. */
+export function findJsonObjectEnd(
+  text: string,
+  start: number,
+  maxPayloadBytes?: number,
+): number | null {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < text.length; index += 1) {
+    if (maxPayloadBytes !== undefined && index + 1 - start > maxPayloadBytes) {
+      return null;
+    }
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return index + 1;
+      }
+    }
+  }
+  return null;
+}
+
+/** Consumes one optional line break after a repaired serialized tool-call fragment. */
+export function skipSerializedToolCallTrailingLineBreak(text: string, cursor: number): number {
+  const afterLineBreak = consumeLineBreak(text, cursor);
+  return afterLineBreak ?? cursor;
+}
+
+/** Accepts the legacy closing markers models append after JSON tool-call payloads. */
+export function consumeJsonToolClosingMarker(text: string, cursor: number): number {
+  let markerStart = cursor;
+  while (markerStart < text.length && /\s/.test(text[markerStart] ?? "")) {
+    markerStart += 1;
+  }
+  const rest = text.slice(markerStart);
+  if (rest.startsWith(END_TOOL_REQUEST)) {
+    return skipSerializedToolCallTrailingLineBreak(text, markerStart + END_TOOL_REQUEST.length);
+  }
+  const bracketClose = /^\[\/[A-Za-z0-9_-]+\]/.exec(rest);
+  if (bracketClose) {
+    return skipSerializedToolCallTrailingLineBreak(text, markerStart + bracketClose[0].length);
+  }
+  if (rest.startsWith(HARMONY_CALL_MARKER)) {
+    return skipSerializedToolCallTrailingLineBreak(text, markerStart + HARMONY_CALL_MARKER.length);
+  }
+  return skipSerializedToolCallTrailingLineBreak(text, cursor);
+}
+
+/** Finds JSON after bracketed tool syntax such as `[tool_name]\n{...}`. */
+export function findBracketedJsonPayloadStart(text: string): number | null {
+  if (!text.startsWith("[")) {
+    return null;
+  }
+  const close = text.indexOf("]");
+  if (close === -1) {
+    return null;
+  }
+  let cursor = close + 1;
+  cursor = skipHorizontalWhitespace(text, cursor);
+  cursor = skipSerializedToolCallTrailingLineBreak(text, cursor);
+  cursor = skipHorizontalWhitespace(text, cursor);
+  return text[cursor] === "{" ? cursor : null;
+}
+
+/** Finds JSON after Harmony channel/tool headers while tolerating optional message markers. */
+export function findHarmonyJsonPayloadStart(text: string): number | null {
+  let cursor = 0;
+  if (text.startsWith(HARMONY_CHANNEL_MARKER)) {
+    cursor = HARMONY_CHANNEL_MARKER.length;
+  }
+  const rest = text.slice(cursor);
+  const channel = ["commentary", "analysis", "final"].find((candidate) =>
+    rest.startsWith(candidate),
+  );
+  if (!channel) {
+    return null;
+  }
+  cursor += channel.length;
+  cursor = skipHorizontalWhitespace(text, cursor);
+  if (!text.slice(cursor).startsWith("to=")) {
+    return null;
+  }
+  cursor += "to=".length;
+  const nameStart = cursor;
+  while (isPlainTextToolNameChar(text[cursor])) {
+    cursor += 1;
+  }
+  if (cursor === nameStart) {
+    return null;
+  }
+  cursor = skipHorizontalWhitespace(text, cursor);
+  if (!text.slice(cursor).startsWith("code")) {
+    return null;
+  }
+  cursor += "code".length;
+  cursor = skipWhitespace(text, cursor);
+  if (text.slice(cursor).startsWith(HARMONY_MESSAGE_MARKER)) {
+    cursor = skipWhitespace(text, cursor + HARMONY_MESSAGE_MARKER.length);
+  }
+  return text[cursor] === "{" ? cursor : null;
+}
+
+/** Case-insensitive marker compare for ASCII protocol tags without locale rules. */
+export function startsWithAsciiMarkerIgnoreCase(
+  text: string,
+  cursor: number,
+  marker: string,
+): boolean {
+  return text.slice(cursor, cursor + marker.length).toLowerCase() === marker;
+}
+
+/** Case-insensitive marker search for ASCII protocol tags without allocating regexes. */
+export function indexOfAsciiMarkerIgnoreCase(text: string, marker: string, start: number): number {
+  let cursor = start;
+  while (cursor < text.length) {
+    const next = text.indexOf(marker[0] ?? "", cursor);
+    if (next === -1) {
+      return -1;
+    }
+    if (startsWithAsciiMarkerIgnoreCase(text, next, marker)) {
+      return next;
+    }
+    cursor = next + 1;
+  }
+  return -1;
+}
+
+/** Returns the end offset for a complete XML-ish or bracketed plain-text tool call. */
+export function findXmlishToolCallEnd(text: string): number | null {
+  let cursor: number;
+  const xmlFunction = /^<function=[A-Za-z0-9_.:-]+>/i.exec(text);
+  if (xmlFunction) {
+    cursor = xmlFunction[0].length;
+  } else {
+    const bracketed = /^\[(?:tool:)?[A-Za-z0-9_-]+\]/.exec(text);
+    if (!bracketed) {
+      return null;
+    }
+    cursor = bracketed[0].length;
+    cursor = skipHorizontalWhitespace(text, cursor);
+    cursor = skipSerializedToolCallTrailingLineBreak(text, cursor);
+  }
+
+  cursor = skipWhitespace(text, cursor);
+  if (!startsWithAsciiMarkerIgnoreCase(text, cursor, "<parameter=")) {
+    return null;
+  }
+
+  while (cursor < text.length) {
+    const parameterClose = indexOfAsciiMarkerIgnoreCase(text, "</parameter>", cursor);
+    if (parameterClose === -1) {
+      return null;
+    }
+    cursor = skipWhitespace(text, parameterClose + "</parameter>".length);
+    if (startsWithAsciiMarkerIgnoreCase(text, cursor, "</function>")) {
+      return skipSerializedToolCallTrailingLineBreak(text, cursor + "</function>".length);
+    }
+    if (!startsWithAsciiMarkerIgnoreCase(text, cursor, "<parameter=")) {
+      return skipSerializedToolCallTrailingLineBreak(text, cursor);
+    }
+  }
+  return null;
+}

packages/tool-call-repair/src/index.ts

@@ -0,0 +1,21 @@
+/** Public repair utilities for model-emitted plain-text tool calls. */
+export {
+  parseStandalonePlainTextToolCallBlocks,
+  stripPlainTextToolCallBlocks,
+  type PlainTextToolCallBlock,
+  type PlainTextToolCallParseOptions,
+} from "./payload.js";
+export {
+  normalizePlainTextToolCallStreamEvents,
+  scrubOverCapPlainTextToolCallMessage,
+  type PlainTextToolCallMessageNormalization,
+  type PlainTextToolCallNameMatcher,
+  type PlainTextToolCallStreamNormalizerOptions,
+} from "./stream-normalizer.js";
+export {
+  extractStandalonePlainTextToolCallText,
+  promoteStandalonePlainTextToolCallMessage,
+  type PlainTextToolCallPromotionOptions,
+  type PromotedPlainTextToolCallBlockFactory,
+  type ToolCallRepairNameResolver,
+} from "./promote.js";

packages/tool-call-repair/src/payload.ts

@@ -0,0 +1,428 @@
+// Tool Call Repair module implements payload behavior.
+import {
+  consumeLineBreak,
+  END_TOOL_REQUEST,
+  findJsonObjectEnd,
+  HARMONY_CALL_MARKER,
+  HARMONY_CHANNEL_MARKER,
+  HARMONY_MESSAGE_MARKER,
+  isPlainTextToolNameChar,
+  skipHorizontalWhitespace,
+  skipWhitespace,
+} from "./grammar.js";
+
+/** Parsed standalone plain-text tool call block with source offsets for repair. */
+export type PlainTextToolCallBlock = {
+  /** Parsed JSON arguments object. */
+  arguments: Record<string, unknown>;
+  /** Exclusive end offset of the parsed block. */
+  end: number;
+  /** Tool name parsed from bracket, Harmony, or XML-ish syntax. */
+  name: string;
+  /** Original text slice that produced this block. */
+  raw: string;
+  /** Inclusive start offset of the parsed block. */
+  start: number;
+};
+
+/** Parser limits and allowlist options for plain-text tool-call repair. */
+export type PlainTextToolCallParseOptions = {
+  /** Optional allowlist of tool names that may be repaired. */
+  allowedToolNames?: Iterable<string>;
+  /** Maximum JSON payload size accepted for one repaired call. */
+  maxPayloadBytes?: number;
+};
+
+const DEFAULT_MAX_PLAIN_TEXT_TOOL_PAYLOAD_BYTES = 256_000;
+
+type PlainTextToolCallOpening = {
+  allowsOptionalXmlishClose?: boolean;
+  end: number;
+  name: string;
+  requiresClosing: boolean;
+};
+
+function parseBracketOpening(text: string, start: number): PlainTextToolCallOpening | null {
+  if (text[start] !== "[") {
+    return null;
+  }
+  let cursor = start + 1;
+  if (text.startsWith("tool:", cursor)) {
+    cursor += "tool:".length;
+    const nameStart = cursor;
+    while (isPlainTextToolNameChar(text[cursor])) {
+      cursor += 1;
+    }
+    if (cursor === nameStart || text[cursor] !== "]") {
+      return null;
+    }
+    return {
+      allowsOptionalXmlishClose: true,
+      end: cursor + 1,
+      name: text.slice(nameStart, cursor),
+      requiresClosing: false,
+    };
+  }
+  const nameStart = cursor;
+  while (isPlainTextToolNameChar(text[cursor])) {
+    cursor += 1;
+  }
+  if (cursor === nameStart || text[cursor] !== "]") {
+    return null;
+  }
+  const name = text.slice(nameStart, cursor);
+  cursor += 1;
+  cursor = skipHorizontalWhitespace(text, cursor);
+  const afterLineBreak = consumeLineBreak(text, cursor);
+  if (afterLineBreak === null) {
+    return null;
+  }
+  return { end: afterLineBreak, name, requiresClosing: true };
+}
+
+function parseHarmonyOpening(text: string, start: number): PlainTextToolCallOpening | null {
+  let cursor = start;
+  if (text.startsWith(HARMONY_CHANNEL_MARKER, cursor)) {
+    cursor += HARMONY_CHANNEL_MARKER.length;
+  }
+  const channelStart = cursor;
+  while (/[A-Za-z_]/.test(text[cursor] ?? "")) {
+    cursor += 1;
+  }
+  const channel = text.slice(channelStart, cursor);
+  if (channel !== "commentary" && channel !== "analysis" && channel !== "final") {
+    return null;
+  }
+  cursor = skipHorizontalWhitespace(text, cursor);
+  if (!text.startsWith("to=", cursor)) {
+    return null;
+  }
+  cursor += 3;
+  const nameStart = cursor;
+  while (isPlainTextToolNameChar(text[cursor])) {
+    cursor += 1;
+  }
+  if (cursor === nameStart) {
+    return null;
+  }
+  const name = text.slice(nameStart, cursor);
+  cursor = skipHorizontalWhitespace(text, cursor);
+  if (!text.startsWith("code", cursor)) {
+    return null;
+  }
+  cursor += 4;
+  cursor = skipWhitespace(text, cursor);
+  if (text.startsWith(HARMONY_MESSAGE_MARKER, cursor)) {
+    cursor = skipWhitespace(text, cursor + HARMONY_MESSAGE_MARKER.length);
+  }
+  return { end: cursor, name, requiresClosing: false };
+}
+
+function parseXmlishFunctionOpening(text: string, start: number): PlainTextToolCallOpening | null {
+  const match = /^<function=([A-Za-z0-9_.:-]{1,120})>\s*/i.exec(text.slice(start));
+  if (!match?.[1]) {
+    return null;
+  }
+  return { end: start + match[0].length, name: match[1], requiresClosing: false };
+}
+
+function parseOpening(text: string, start: number): PlainTextToolCallOpening | null {
+  return parseBracketOpening(text, start) ?? parseHarmonyOpening(text, start);
+}
+
+function consumeJsonObject(
+  text: string,
+  start: number,
+  maxPayloadBytes: number,
+): { end: number; value: Record<string, unknown> } | null {
+  const cursor = skipWhitespace(text, start);
+  if (text[cursor] !== "{") {
+    return null;
+  }
+  const end = findJsonObjectEnd(text, cursor, maxPayloadBytes);
+  if (end === null) {
+    return null;
+  }
+  const rawJson = text.slice(cursor, end);
+  try {
+    const parsed = JSON.parse(rawJson) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return { end, value: parsed as Record<string, unknown> };
+  } catch {
+    return null;
+  }
+}
+
+function parseClosing(text: string, start: number, name: string): number | null {
+  const cursor = skipWhitespace(text, start);
+  if (text.startsWith(END_TOOL_REQUEST, cursor)) {
+    return cursor + END_TOOL_REQUEST.length;
+  }
+  const namedClosing = `[/${name}]`;
+  if (text.startsWith(namedClosing, cursor)) {
+    return cursor + namedClosing.length;
+  }
+  return null;
+}
+
+function parseOptionalHarmonyClosing(text: string, start: number): number {
+  const cursor = skipWhitespace(text, start);
+  if (text.startsWith(HARMONY_CALL_MARKER, cursor)) {
+    return cursor + HARMONY_CALL_MARKER.length;
+  }
+  return start;
+}
+
+function parsePlainTextToolCallBlockAt(
+  text: string,
+  start: number,
+  options?: PlainTextToolCallParseOptions,
+): PlainTextToolCallBlock | null {
+  const opening = parseOpening(text, start);
+  if (!opening) {
+    return null;
+  }
+  const allowedToolNames = options?.allowedToolNames
+    ? new Set(options.allowedToolNames)
+    : undefined;
+  if (allowedToolNames && !allowedToolNames.has(opening.name)) {
+    return null;
+  }
+  const payload = consumeJsonObject(
+    text,
+    opening.end,
+    options?.maxPayloadBytes ?? DEFAULT_MAX_PLAIN_TEXT_TOOL_PAYLOAD_BYTES,
+  );
+  if (!payload) {
+    return null;
+  }
+  const closingEnd = opening.requiresClosing
+    ? parseClosing(text, payload.end, opening.name)
+    : parseOptionalHarmonyClosing(text, payload.end);
+  if (closingEnd === null) {
+    return null;
+  }
+  return {
+    arguments: payload.value,
+    end: closingEnd,
+    name: opening.name,
+    raw: text.slice(start, closingEnd),
+    start,
+  };
+}
+
+type XmlishParameterBlockBounds = {
+  closeStart: number;
+  end: number;
+  name: string;
+  payloadStart: number;
+  start: number;
+};
+
+function findXmlishParameterBlock(text: string, start: number): XmlishParameterBlockBounds | null {
+  const cursor = skipWhitespace(text, start);
+  const openMatch = /^<parameter=([A-Za-z0-9_.:-]{1,120})>/i.exec(text.slice(cursor));
+  if (!openMatch?.[1]) {
+    return null;
+  }
+  const payloadStart = cursor + openMatch[0].length;
+  const closeMatch = /<\/parameter>/i.exec(text.slice(payloadStart));
+  if (!closeMatch) {
+    return null;
+  }
+  const closeStart = payloadStart + closeMatch.index;
+  const closeEnd = closeStart + closeMatch[0].length;
+  return {
+    closeStart,
+    end: closeEnd,
+    name: openMatch[1],
+    payloadStart,
+    start: cursor,
+  };
+}
+
+function consumeXmlishParameterBlock(
+  text: string,
+  start: number,
+  maxPayloadBytes: number,
+): { end: number; name: string; value: string } | null {
+  const bounds = findXmlishParameterBlock(text, start);
+  if (!bounds) {
+    return null;
+  }
+  if (bounds.end - bounds.start > maxPayloadBytes) {
+    return null;
+  }
+  return {
+    end: bounds.end,
+    name: bounds.name,
+    value: extractXmlishParameterValue(text, bounds.payloadStart, bounds.closeStart),
+  };
+}
+
+function extractXmlishParameterValue(text: string, start: number, end: number): string {
+  let payloadStart = start;
+  let payloadEnd = end;
+  const afterOpeningLineBreak = consumeLineBreak(text, payloadStart);
+  if (afterOpeningLineBreak !== null) {
+    payloadStart = afterOpeningLineBreak;
+    if (payloadEnd > payloadStart && text[payloadEnd - 1] === "\n") {
+      payloadEnd -= 1;
+      if (payloadEnd > payloadStart && text[payloadEnd - 1] === "\r") {
+        payloadEnd -= 1;
+      }
+    } else if (payloadEnd > payloadStart && text[payloadEnd - 1] === "\r") {
+      payloadEnd -= 1;
+    }
+  }
+  return text.slice(payloadStart, payloadEnd);
+}
+
+function consumeXmlishFunctionClose(text: string, start: number): number | null {
+  const cursor = skipWhitespace(text, start);
+  return text.slice(cursor).toLowerCase().startsWith("</function>")
+    ? cursor + "</function>".length
+    : null;
+}
+
+function consumeOptionalXmlishFunctionClose(text: string, start: number): number {
+  return consumeXmlishFunctionClose(text, start) ?? start;
+}
+
+function parseXmlishPlainTextToolCallBlockEndAt(text: string, start: number): number | null {
+  const opening = parseXmlishOpening(text, start);
+  if (!opening) {
+    return null;
+  }
+
+  let cursor = opening.end;
+  let parameterCount = 0;
+  while (true) {
+    const parameter = findXmlishParameterBlock(text, cursor);
+    if (!parameter) {
+      break;
+    }
+    parameterCount += 1;
+    cursor = parameter.end;
+  }
+  if (parameterCount === 0) {
+    return null;
+  }
+  return opening.allowsOptionalXmlishClose
+    ? consumeOptionalXmlishFunctionClose(text, cursor)
+    : consumeXmlishFunctionClose(text, cursor);
+}
+
+function parseXmlishOpening(text: string, start: number): PlainTextToolCallOpening | null {
+  return parseBracketOpening(text, start) ?? parseXmlishFunctionOpening(text, start);
+}
+
+function parseXmlishPlainTextToolCallBlockAt(
+  text: string,
+  start: number,
+  options?: PlainTextToolCallParseOptions,
+): PlainTextToolCallBlock | null {
+  const opening = parseXmlishOpening(text, start);
+  if (!opening) {
+    return null;
+  }
+  const allowedToolNames = options?.allowedToolNames
+    ? new Set(options.allowedToolNames)
+    : undefined;
+  if (allowedToolNames && !allowedToolNames.has(opening.name)) {
+    return null;
+  }
+
+  const maxPayloadBytes = options?.maxPayloadBytes ?? DEFAULT_MAX_PLAIN_TEXT_TOOL_PAYLOAD_BYTES;
+  const args: Record<string, unknown> = {};
+  let cursor = opening.end;
+  let parameterCount = 0;
+  while (true) {
+    const parameter = consumeXmlishParameterBlock(text, cursor, maxPayloadBytes);
+    if (!parameter) {
+      break;
+    }
+    if (parameter.end - opening.end > maxPayloadBytes) {
+      return null;
+    }
+    args[parameter.name] = parameter.value;
+    parameterCount += 1;
+    cursor = parameter.end;
+  }
+  if (parameterCount === 0) {
+    return null;
+  }
+
+  const end = opening.allowsOptionalXmlishClose
+    ? consumeOptionalXmlishFunctionClose(text, cursor)
+    : consumeXmlishFunctionClose(text, cursor);
+  if (end === null) {
+    return null;
+  }
+  return {
+    arguments: args,
+    end,
+    name: opening.name,
+    raw: text.slice(start, end),
+    start,
+  };
+}
+
+export function parseStandalonePlainTextToolCallBlocks(
+  text: string,
+  options?: PlainTextToolCallParseOptions,
+): PlainTextToolCallBlock[] | null {
+  const blocks: PlainTextToolCallBlock[] = [];
+  let cursor = skipWhitespace(text, 0);
+  while (cursor < text.length) {
+    const block =
+      parsePlainTextToolCallBlockAt(text, cursor, options) ??
+      parseXmlishPlainTextToolCallBlockAt(text, cursor, options);
+    if (!block) {
+      return null;
+    }
+    blocks.push(block);
+    cursor = skipWhitespace(text, block.end);
+  }
+  return blocks.length > 0 ? blocks : null;
+}
+
+/** Removes full-line standalone plain-text tool-call blocks from user-visible text. */
+export function stripPlainTextToolCallBlocks(text: string): string {
+  if (
+    !text ||
+    (!/\[(?:tool:)?[A-Za-z0-9_-]+\]/.test(text) &&
+      !/(?:^|\n)\s*(?:<\|channel\|>)?(?:commentary|analysis|final)\s+to=/.test(text) &&
+      !/(?:^|\n)\s*<function=[A-Za-z0-9_.:-]{1,120}>/i.test(text))
+  ) {
+    return text;
+  }
+  let result = "";
+  let cursor = 0;
+  let index = 0;
+  while (index < text.length) {
+    const lineStart = index === 0 || text[index - 1] === "\n";
+    if (!lineStart) {
+      index += 1;
+      continue;
+    }
+    const blockStart = skipHorizontalWhitespace(text, index);
+    const block = parsePlainTextToolCallBlockAt(text, blockStart);
+    const blockEnd = block?.end ?? parseXmlishPlainTextToolCallBlockEndAt(text, blockStart);
+    if (blockEnd === null) {
+      index += 1;
+      continue;
+    }
+    result += text.slice(cursor, index);
+    cursor = blockEnd;
+    const afterBlockLineBreak = consumeLineBreak(text, cursor);
+    if (afterBlockLineBreak !== null) {
+      cursor = afterBlockLineBreak;
+    }
+    index = cursor;
+  }
+  result += text.slice(cursor);
+  return result;
+}

packages/tool-call-repair/src/promote.ts

@@ -0,0 +1,265 @@
+// Tool Call Repair module implements promote behavior.
+import { parseStandalonePlainTextToolCallBlocks, type PlainTextToolCallBlock } from "./payload.js";
+
+/** Resolves model-emitted tool names to the exact names allowed by the provider request. */
+export type ToolCallRepairNameResolver = (
+  rawName: string,
+  allowedToolNames: Set<string>,
+) => string | null;
+
+/** Builds a provider-native tool-call block from a repaired plain-text payload. */
+export type PromotedPlainTextToolCallBlockFactory = (
+  block: PlainTextToolCallBlock,
+  resolvedName: string,
+) => Record<string, unknown>;
+
+/** Controls when standalone assistant text may be rewritten as tool-call content. */
+export type PlainTextToolCallPromotionOptions = {
+  allowedStopReasons?: ReadonlySet<unknown>;
+  allowedToolNames: Set<string>;
+  createToolCallBlock: PromotedPlainTextToolCallBlockFactory;
+  isRetainableNonTextBlock?: (block: Record<string, unknown>) => boolean;
+  message: unknown;
+  requireAssistantRole?: boolean;
+  resolveToolName?: ToolCallRepairNameResolver;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+}
+
+function resolveExactToolName(rawName: string, allowedToolNames: Set<string>): string | null {
+  return allowedToolNames.has(rawName) ? rawName : null;
+}
+
+function createPromotedToolCallBlocks(
+  text: string,
+  options: PlainTextToolCallPromotionOptions,
+): Record<string, unknown>[] | undefined {
+  const parsedBlocks = parseStandalonePlainTextToolCallBlocks(text);
+  if (!parsedBlocks) {
+    return undefined;
+  }
+
+  const resolveToolName = options.resolveToolName ?? resolveExactToolName;
+  const toolCalls: Record<string, unknown>[] = [];
+  for (const block of parsedBlocks) {
+    const resolvedName = resolveToolName(block.name, options.allowedToolNames);
+    if (!resolvedName) {
+      return undefined;
+    }
+    toolCalls.push(options.createToolCallBlock(block, resolvedName));
+  }
+  return toolCalls;
+}
+
+function createPromotedToolCallBlocksFromTextParts(
+  textParts: readonly string[],
+  options: PlainTextToolCallPromotionOptions,
+): Record<string, unknown>[] | undefined {
+  const exactText = textParts.join("").trim();
+  if (!exactText) {
+    return [];
+  }
+  for (const text of createTextPartPromotionCandidates(textParts, exactText)) {
+    const toolCalls = createPromotedToolCallBlocks(text, options);
+    if (toolCalls) {
+      return toolCalls;
+    }
+  }
+  return undefined;
+}
+
+function createTextPartPromotionCandidates(
+  textParts: readonly string[],
+  exactText: string,
+): string[] {
+  // Some providers split structural markers across text parts; try repaired and exact joins
+  // before falling back to newline joins so valid payloads promote without changing content.
+  const repairedText = joinTextPartsWithStructuralLineBreaks(textParts).trim();
+  const newlineJoinedText = textParts.join("\n").trim();
+  return [...new Set([repairedText, exactText, newlineJoinedText].filter(Boolean))];
+}
+
+function joinTextPartsWithStructuralLineBreaks(textParts: readonly string[]): string {
+  let text = "";
+  for (const part of textParts) {
+    if (text && shouldInsertStructuralLineBreak(text, part)) {
+      text += "\n";
+    }
+    text += part;
+  }
+  return text;
+}
+
+function shouldInsertStructuralLineBreak(left: string, right: string): boolean {
+  if (!left || !right || /[\r\n]$/u.test(left) || /^\s/u.test(right)) {
+    return false;
+  }
+  const trimmedLeft = left.trimEnd();
+  return (
+    /<parameter=[A-Za-z0-9_.:-]{1,120}>$/iu.test(trimmedLeft) ||
+    /^\[[A-Za-z0-9_-]+\]$/u.test(trimmedLeft)
+  );
+}
+
+function shouldPromoteMessage(options: PlainTextToolCallPromotionOptions): boolean {
+  if (options.allowedToolNames.size === 0) {
+    return false;
+  }
+  const messageRecord = asRecord(options.message);
+  if (!messageRecord) {
+    return false;
+  }
+  if (options.requireAssistantRole && messageRecord.role !== "assistant") {
+    return false;
+  }
+  return !options.allowedStopReasons || options.allowedStopReasons.has(messageRecord.stopReason);
+}
+
+/** Extracts candidate standalone tool-call text while rejecting mixed unsafe content. */
+export function extractStandalonePlainTextToolCallText(params: {
+  allowOtherNonTextBlocks?: boolean;
+  allowedStopReasons?: ReadonlySet<unknown>;
+  isRetainableNonTextBlock?: (block: Record<string, unknown>) => boolean;
+  message: unknown;
+  requireAssistantRole?: boolean;
+}): string | undefined {
+  const record = asRecord(params.message);
+  if (!record) {
+    return undefined;
+  }
+  if (params.requireAssistantRole && record.role !== "assistant") {
+    return undefined;
+  }
+  if (params.allowedStopReasons && !params.allowedStopReasons.has(record.stopReason)) {
+    return undefined;
+  }
+
+  const content = record.content;
+  if (typeof content === "string") {
+    const text = content.trim();
+    return text || undefined;
+  }
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+
+  const textParts: string[] = [];
+  for (const block of content) {
+    const blockRecord = asRecord(block);
+    if (!blockRecord) {
+      return undefined;
+    }
+    if (blockRecord.type === "text") {
+      if (typeof blockRecord.text !== "string") {
+        return undefined;
+      }
+      if (blockRecord.text.trim()) {
+        textParts.push(blockRecord.text);
+      }
+      continue;
+    }
+    if (params.isRetainableNonTextBlock?.(blockRecord) || params.allowOtherNonTextBlocks) {
+      continue;
+    }
+    return undefined;
+  }
+
+  const text = textParts.join("").trim();
+  return text || undefined;
+}
+
+/** Promotes standalone plain-text tool-call messages into provider-native content blocks. */
+export function promoteStandalonePlainTextToolCallMessage(
+  options: PlainTextToolCallPromotionOptions,
+): Record<string, unknown> | undefined {
+  if (!shouldPromoteMessage(options)) {
+    return undefined;
+  }
+  const messageRecord = asRecord(options.message);
+  if (!messageRecord) {
+    return undefined;
+  }
+
+  const originalContent = messageRecord.content;
+  if (typeof originalContent === "string") {
+    const text = originalContent.trim();
+    if (!text) {
+      return undefined;
+    }
+    const toolCalls = createPromotedToolCallBlocks(text, options);
+    if (!toolCalls) {
+      return undefined;
+    }
+    return {
+      ...messageRecord,
+      content: toolCalls,
+      stopReason: "toolUse",
+    };
+  }
+
+  if (!Array.isArray(originalContent)) {
+    return undefined;
+  }
+
+  const content: Array<Record<string, unknown>> = [];
+  let promotedTextBlock = false;
+  let textParts: string[] = [];
+  const flushTextParts = (): boolean | undefined => {
+    if (textParts.length === 0) {
+      return false;
+    }
+    const toolCalls = createPromotedToolCallBlocksFromTextParts(textParts, options);
+    textParts = [];
+    if (toolCalls?.length === 0) {
+      return false;
+    }
+    if (!toolCalls) {
+      return undefined;
+    }
+    content.push(...toolCalls);
+    return true;
+  };
+
+  for (const block of originalContent) {
+    const blockRecord = asRecord(block);
+    if (!blockRecord) {
+      return undefined;
+    }
+    if (blockRecord.type === "text") {
+      if (typeof blockRecord.text !== "string") {
+        return undefined;
+      }
+      if (blockRecord.text.trim()) {
+        textParts.push(blockRecord.text);
+      }
+      continue;
+    }
+    const promotedTextRun = flushTextParts();
+    if (promotedTextRun === undefined) {
+      return undefined;
+    }
+    promotedTextBlock ||= promotedTextRun;
+    if (options.isRetainableNonTextBlock?.(blockRecord)) {
+      content.push(blockRecord);
+      continue;
+    }
+    return undefined;
+  }
+
+  const promotedTrailingTextRun = flushTextParts();
+  if (promotedTrailingTextRun === undefined) {
+    return undefined;
+  }
+  promotedTextBlock ||= promotedTrailingTextRun;
+  if (!promotedTextBlock) {
+    return undefined;
+  }
+
+  return {
+    ...messageRecord,
+    content,
+    stopReason: "toolUse",
+  };
+}