dsh-ptc-plus 0.2.1

package/internal/program-bindings.js

@@ -0,0 +1,187 @@
+/** Deterministic capability metadata derived from the current DSH tool view. */
+import { record, text } from './record-utils.js'
+
+const COMPLETENESS = new Set(['complete', 'bounded', 'incremental', 'open-world', 'unknown'])
+const SOURCE_KINDS = new Set(['authored', 'runtime', 'tests', 'docs'])
+const REPLAY = new Set(['recorded-value', 'owner-replay', 'volatile', 'unknown'])
+
+
+function metadataSnapshot(value, label) {
+  let clone
+  try {
+    clone = structuredClone(value)
+  } catch (error) {
+    throw new TypeError(`ptc-plus: ${label} must be structured data: ${error.message}`)
+  }
+  if (clone === null || typeof clone !== 'object') return clone
+  const pending = [clone]
+  const seen = new Set()
+  while (pending.length > 0) {
+    const current = pending.pop()
+    if (seen.has(current)) continue
+    seen.add(current)
+    for (const child of Object.values(current)) {
+      if (child !== null && typeof child === 'object') pending.push(child)
+    }
+    Object.freeze(current)
+  }
+  return clone
+}
+
+function sourceRef(value, label) {
+  if (value === undefined) return undefined
+  const source = record(value, label)
+  const kind = text(source.kind, `${label}.kind`)
+  if (!SOURCE_KINDS.has(kind)) throw new TypeError(`ptc-plus: ${label}.kind is invalid`)
+  const path = text(source.path, `${label}.path`)
+  const result = { kind, path }
+  if (source.symbol !== undefined) result.symbol = text(source.symbol, `${label}.symbol`)
+  if (source.revision !== undefined) result.revision = text(source.revision, `${label}.revision`)
+  return Object.freeze(result)
+}
+
+/** Convert DSH's live tool schemas into descriptive metadata without wrapping invocation. */
+export function toolCapabilityMetadata(schemas, annotations = {}) {
+  if (!Array.isArray(schemas)) throw new TypeError('ptc-plus: tool schemas must be an array')
+  const overrides = record(annotations, 'tool annotations')
+  const members = schemas
+    .filter(schema => schema?.name !== 'run_code')
+    .map((schema) => {
+      const value = record(schema, 'tool schema')
+      const name = text(value.name, 'tool schema name')
+      const annotation = overrides[name] === undefined ? {} : record(overrides[name], `${name} annotation`)
+      return Object.freeze({
+        name,
+        ...(value.description === undefined ? {} : { description: text(value.description, `${name} description`) }),
+        parameters: metadataSnapshot(value.parameters ?? {}, `${name} parameters`),
+        returns: metadataSnapshot(value.output ?? {}, `${name} output`),
+        effect: annotation.effect ?? 'unknown',
+        authority: annotation.authority ?? 'dsh-tool-dispatch',
+        completeness: annotation.completeness ?? 'unknown',
+        replay: annotation.replay ?? 'unknown',
+        ...(annotation.sourceRef === undefined ? {} : { sourceRef: sourceRef(annotation.sourceRef, `${name} sourceRef`) }),
+        ...(annotation.revision === undefined ? {} : { revision: text(annotation.revision, `${name} revision`) }),
+        ...(annotation.fingerprint === undefined ? {} : { fingerprint: text(annotation.fingerprint, `${name} fingerprint`) }),
+      })
+    })
+    .sort((left, right) => left.name.localeCompare(right.name))
+  for (const member of members) {
+    if (!COMPLETENESS.has(member.completeness)) {
+      throw new TypeError(`ptc-plus: ${member.name}.completeness is invalid`)
+    }
+    if (!REPLAY.has(member.replay)) {
+      throw new TypeError(`ptc-plus: ${member.name}.replay is invalid`)
+    }
+  }
+  return Object.freeze([{ namespace: 'tools', members: Object.freeze(members) }])
+}
+
+function metadataEntries(metadata) {
+  if (!Array.isArray(metadata)) throw new TypeError('ptc-plus: capability metadata must be an array')
+  return metadata.map((entry) => {
+    const value = record(entry, 'capability metadata entry')
+    const namespace = text(value.namespace, 'capability namespace')
+    const members = Array.isArray(value.members)
+      ? value.members.map((member) => {
+          const item = record(member, 'capability member')
+          return { ...item, name: text(item.name, `${namespace} capability member name`) }
+        })
+      : []
+    return { ...value, namespace, members }
+  })
+}
+
+function searchTokens(value) {
+  const separated = value
+    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1 $2')
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1 $2')
+  return separated.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []
+}
+
+function includesTokenSequence(tokens, queryTokens) {
+  if (queryTokens.length === 0 || queryTokens.length > tokens.length) return false
+  return tokens.some((_, start) => queryTokens.every(
+    (token, offset) => tokens[start + offset] === token,
+  ))
+}
+
+function capabilityMatchRank(namespace, member, query, queryTokens) {
+  const normalizedNamespace = namespace.toLowerCase()
+  const normalizedMember = member.name.toLowerCase()
+  const symbol = `${normalizedNamespace}.${normalizedMember}`
+  if (symbol === query) return 0
+  if (normalizedNamespace === query) return 1
+  if (normalizedMember === query) return 2
+  if (includesTokenSequence(searchTokens(`${namespace}.${member.name}`), queryTokens)) return 3
+  if (typeof member.description === 'string'
+    && includesTokenSequence(searchTokens(member.description), queryTokens)) return 4
+  return undefined
+}
+
+/** Deterministic hierarchy only. Details remain behind inspect. */
+export function capabilityTree(metadata) {
+  return metadataEntries(metadata).map((value) => {
+    return {
+      namespace: value.namespace,
+      members: value.members.map(member => member.name),
+      ...(value.revision === undefined ? {} : { revision: value.revision }),
+      ...(value.fingerprint === undefined ? {} : { fingerprint: value.fingerprint }),
+    }
+  })
+}
+
+/** Find lightweight candidates without returning full schemas or source. */
+export function capabilityFind(metadata, query) {
+  const trimmedQuery = text(query, 'capability query').trim()
+  const normalizedQuery = trimmedQuery.toLowerCase()
+  const queryTokens = searchTokens(trimmedQuery)
+  const candidates = []
+  let order = 0
+  for (const entry of metadataEntries(metadata)) {
+    for (const member of entry.members) {
+      const rank = capabilityMatchRank(entry.namespace, member, normalizedQuery, queryTokens)
+      if (rank !== undefined) {
+        candidates.push({
+          rank,
+          order,
+          value: {
+            symbol: `${entry.namespace}.${member.name}`,
+            ...(member.description === undefined ? {} : { description: member.description }),
+            completeness: member.completeness ?? 'unknown',
+            effect: member.effect ?? 'unknown',
+            replay: member.replay ?? 'unknown',
+          },
+        })
+      }
+      order += 1
+    }
+  }
+  return candidates
+    .sort((left, right) => left.rank - right.rank || left.order - right.order)
+    .map(candidate => candidate.value)
+}
+
+/** Batch, budgeted inspection; omitted items remain explicit to the caller. */
+export function capabilityInspect(metadata, symbols = undefined, budget = 50) {
+  if (!Number.isSafeInteger(budget) || budget < 1) throw new TypeError('ptc-plus: capability inspection budget must be a positive integer')
+  const entries = metadataEntries(metadata)
+  const requested = symbols === undefined
+    ? entries.flatMap(entry => entry.members.map(member => `${entry.namespace}.${member.name}`))
+    : symbols
+  if (!Array.isArray(requested)) throw new TypeError('ptc-plus: capability symbols must be an array')
+  const bySymbol = new Map(entries.flatMap(entry => entry.members.map(member => [
+    `${entry.namespace}.${member.name}`,
+    { namespace: entry.namespace, ...member },
+  ])))
+  const selected = requested.slice(0, budget).flatMap((symbol) => {
+    const key = text(symbol, 'capability symbol')
+    const found = bySymbol.get(key)
+    return found === undefined ? [] : [found]
+  })
+  return {
+    symbols: selected,
+    omitted: Math.max(0, requested.length - budget),
+    unknown: requested.slice(0, budget).filter(symbol => !bySymbol.has(symbol)),
+    budget,
+  }
+}

package/internal/record-utils.js

@@ -0,0 +1,53 @@
+/** Shared structural guards for closed PTC metadata boundaries. */
+
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function assertOwnFields(value, allowed, label) {
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== 'string' || !allowed.has(key)
+      || !Object.prototype.propertyIsEnumerable.call(value, key)) {
+      throw new TypeError(`invalid ${label} field ${String(key)}`)
+    }
+  }
+}
+
+export function assertFields(value, allowed, label) {
+  if (!isRecord(value)) throw new TypeError(`invalid ${label}`)
+  assertOwnFields(value, allowed, label)
+  if (Reflect.ownKeys(value).length !== allowed.size) throw new TypeError(`invalid ${label} fields`)
+}
+
+export function record(value, label) {
+  if (!isRecord(value)) throw new TypeError(`ptc-plus: ${label} must be an object`)
+  return value
+}
+
+export function text(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`ptc-plus: ${label} must be a non-empty string`)
+  }
+  return value
+}
+
+/** Freeze one static object graph without invoking accessors or recursing. */
+export function deepFreeze(value) {
+  if (value === null || typeof value !== 'object') return value
+  const pending = [value]
+  const seen = new Set()
+  while (pending.length > 0) {
+    const current = pending.pop()
+    if (seen.has(current)) continue
+    seen.add(current)
+    for (const key of Reflect.ownKeys(current)) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key)
+      if (descriptor !== undefined && Object.hasOwn(descriptor, 'value')) {
+        const child = descriptor.value
+        if (child !== null && typeof child === 'object') pending.push(child)
+      }
+    }
+    Object.freeze(current)
+  }
+  return value
+}

package/internal/recovery-tips.js

@@ -0,0 +1,81 @@
+const PLATFORM_CAUSE_CODES = new Set(['EACCES', 'EINVAL', 'ENOTDIR', 'ENOENT', 'UNKNOWN'])
+const TIP_CONTEXT_PREFIX = 'tools:ptc-plus-tip/'
+export const LONG_FAILED_CELL_TIP_CODE_UNITS = 2_000
+const TIP_PREFIXES = Object.freeze({
+  'repeated-binding-failure': 'The same binding failure has recurred.',
+  'platform-command-failure': 'An executable, shell, or path failed in the current execution world.',
+})
+
+// TODO(dsh-tips-api): replace this local provider with an adapter after dsh-tips publishes a stable facts and decision interface.
+function tipHistory(view) {
+  const active = new Map()
+  const seen = new Set()
+  const history = []
+  for (const snapshot of view.systemPromptSnapshots) {
+    const next = new Map(snapshot.sections.map(section => [section.name, section.text]))
+    for (const [name] of next) {
+      if (active.has(name) || seen.has(name)) continue
+      const match = /^tools:ptc-plus-tip\/(repeated-binding-failure|platform-command-failure)\/([1-9][0-9]*)$/.exec(name)
+      if (match === null) continue
+      const ordinal = Number(match[2])
+      if (!Number.isSafeInteger(ordinal)) continue
+      seen.add(name)
+      history.push({ id: match[1], ordinal, index: snapshot.index, contextStep: snapshot.contextStep })
+    }
+    active.clear()
+    for (const entry of next) active.set(...entry)
+  }
+  return history
+}
+
+function hasPlatformCommandDiagnostic(diagnostics) {
+  return diagnostics.some(diagnostic => {
+    if (diagnostic.code !== 'PTC-X001') return false
+    const parts = [diagnostic.message, diagnostic.cause?.code, diagnostic.cause?.message]
+      .filter(value => typeof value === 'string')
+    const text = parts.join('\n')
+    const causeCode = typeof diagnostic.cause?.code === 'string' ? diagnostic.cause.code.toUpperCase() : undefined
+    if (causeCode !== undefined && PLATFORM_CAUSE_CODES.has(causeCode)
+      && /\b(?:spawn|exec(?:ute)?|command|executable|shell|path|file)\b/i.test(text)) return true
+    return /(?:spawn|exec(?:ute)?|child process)\b.*(?:failed|error|not found|cannot find)/i.test(text)
+      || /command not found|no such file|not recognized as (?:an )?internal|cannot find (?:the )?(?:path|file)/i.test(text)
+  })
+}
+
+function tipCandidate(view) {
+  const { args, journal } = view.latestRun ?? {}
+  if (args === undefined || journal === undefined) return undefined
+  const codes = new Set(journal.diagnostics.map(diagnostic => diagnostic.code))
+  if (codes.has('PTC-W001')) return { id: 'repeated-binding-failure' }
+  if (hasPlatformCommandDiagnostic(journal.diagnostics)) return { id: 'platform-command-failure' }
+  return undefined
+}
+
+function renderTip(id, detailed, candidate = {}) {
+  if (id === 'platform-command-failure') {
+    return detailed
+      ? `${TIP_PREFIXES[id]} Re-check the active execution world and the actual executable before retrying. Use direct argv for a normal executable; use a shell only when its syntax or resolution is required. Windows, WSL, POSIX, and package shims have different paths and launch rules.`
+      : `${TIP_PREFIXES[id]} Inspect the executable or path in the current execution world and choose direct argv or a shell only when required; do not assume Windows, WSL, POSIX, or one shell.`
+  }
+  return detailed
+    ? `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`. Do not invent hidden bindings or repeat the same failing expression.`
+    : `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`.`
+}
+
+export function latestRecoveryTip(view, config) {
+  if (!config.enabled) return undefined
+  const candidate = tipCandidate(view)
+  if (candidate === undefined) return undefined
+  const history = tipHistory(view)
+  const lastTip = history.at(-1)
+  if (lastTip !== undefined && view.contextStep - lastTip.contextStep < config.cooldownMessages) return undefined
+  const unresolved = history.filter(item => item.id === candidate.id && item.index > (view.lastSuccessfulRunIndex ?? -1))
+  const ordinal = history.reduce(
+    (highest, item) => item.id === candidate.id ? Math.max(highest, item.ordinal) : highest,
+    0,
+  ) + 1
+  return {
+    name: `${TIP_CONTEXT_PREFIX}${candidate.id}/${ordinal}`,
+    text: renderTip(candidate.id, unresolved.length >= config.escalationFailures, candidate),
+  }
+}

package/internal/rejected-cell-editor.js

@@ -0,0 +1,328 @@
+import { runInNewContext } from 'node:vm'
+
+const DEFAULT_REGEX_TIMEOUT_MS = 100
+export const EDIT_LIMITS = Object.freeze({
+  exactEdits: 16,
+  exactSearchCodeUnits: 16 * 1024 * 1024,
+  regexEdits: 16,
+  regexMatches: 4_096,
+  regexTemplateCodeUnits: 16 * 1024,
+  regexExpansionSteps: 64 * 1024,
+  regexCaptureSlots: 64 * 1024,
+  generatedCodeUnits: 1024 * 1024,
+})
+
+const EDIT_RUN_CODE_EXECUTION_DESCRIPTION = 'Edit and run TypeScript cell'
+const REGEX_EDIT_RUN_CODE_EXECUTION_DESCRIPTION = 'Regex-edit and run TypeScript cell'
+
+const REGEX_MATCH_SCRIPT = `(() => {
+  const replacements = []
+  let captureSlots = 0
+  for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+    const rule = rules[ruleIndex]
+    let expression
+    try {
+      expression = new RegExp(rule.pattern, (rule.flags.includes('g') ? rule.flags : rule.flags + 'g') + 'd')
+    } catch (error) {
+      return { error: 'regex_edits[' + ruleIndex + '].pattern is invalid: ' + error.message }
+    }
+    let count = 0
+    for (const match of source.matchAll(expression)) {
+      if (match[0].length === 0) {
+        return { error: 'regex_edits[' + ruleIndex + '] must not produce zero-length matches' }
+      }
+      count += 1
+      if (count > rule.expected_matches) break
+      captureSlots += match.indices.length - 1
+      if (captureSlots > maxCaptureSlots) {
+        return { error: 'regex_edits exceed the ' + maxCaptureSlots + ' capture-slot budget' }
+      }
+      const named = match.indices.groups
+      replacements.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        captures: Array.from(match.indices).slice(1),
+        groups: named === undefined
+          ? undefined
+          : Object.fromEntries(Object.entries(named)),
+        ruleIndex,
+      })
+    }
+    if (count !== rule.expected_matches) {
+      return {
+        error: 'regex_edits[' + ruleIndex + '] expected ' + rule.expected_matches
+          + (count > rule.expected_matches
+              ? ' matches but found more than ' + rule.expected_matches
+              : ' matches but found ' + count),
+      }
+    }
+  }
+  return { replacements }
+})()`
+
+function rejection(reason) {
+  return Object.freeze({ edited: false, reason })
+}
+
+function exactReplacements(edits, source) {
+  if (edits.length === 0) return { error: 'edits must contain at least one replacement' }
+  if (edits.length > EDIT_LIMITS.exactEdits) {
+    return { error: `edits must contain at most ${EDIT_LIMITS.exactEdits} replacements` }
+  }
+  for (const [index, edit] of edits.entries()) {
+    if (edit === null || typeof edit !== 'object' || Array.isArray(edit)) {
+      return { error: `edits[${index}] must be an object` }
+    }
+    const keys = Object.keys(edit)
+    if (keys.length !== 2 || !keys.includes('old_string') || !keys.includes('new_string')
+      || typeof edit.old_string !== 'string' || typeof edit.new_string !== 'string') {
+      return { error: `edits[${index}] expects exactly old_string and new_string strings` }
+    }
+    if (edit.old_string.length === 0) return { error: `edits[${index}].old_string must be non-empty` }
+    if (edit.old_string === edit.new_string) {
+      return { error: `edits[${index}].old_string and new_string must differ` }
+    }
+  }
+  const searchWork = source.length * edits.length * 2
+  if (!Number.isSafeInteger(searchWork) || searchWork > EDIT_LIMITS.exactSearchCodeUnits) {
+    return { error: `edits exceed the ${EDIT_LIMITS.exactSearchCodeUnits} source-code-unit search budget` }
+  }
+  const replacements = []
+  for (const [index, edit] of edits.entries()) {
+    const start = source.indexOf(edit.old_string)
+    if (start < 0) return { error: `edits[${index}].old_string was not found in the target cell` }
+    if (source.indexOf(edit.old_string, start + 1) >= 0) {
+      return { error: `edits[${index}].old_string occurs more than once in the target cell` }
+    }
+    replacements.push({ start, end: start + edit.old_string.length, text: edit.new_string, index })
+  }
+  return { replacements }
+}
+
+function replacementParts(template) {
+  const parts = []
+  let cursor = 0
+  for (const token of template.matchAll(/\$(\$|&|`|'|\d{1,2}|<([^>]*)>)/g)) {
+    if (token.index > cursor) parts.push(template.slice(cursor, token.index))
+    parts.push({ token: token[0], marker: token[1], groupName: token[2] })
+    cursor = token.index + token[0].length
+  }
+  if (cursor < template.length) parts.push(template.slice(cursor))
+  return parts
+}
+
+function sourcePart(range, suffix = '') {
+  return range === undefined
+    ? { text: suffix }
+    : { start: range[0], end: range[1], suffix }
+}
+
+function resolvePart(part, match, sourceLength) {
+  if (typeof part === 'string') return { text: part }
+  const { token, marker, groupName } = part
+  if (marker === '$') return { text: '$' }
+  if (marker === '&') return sourcePart([match.start, match.end])
+  if (marker === '`') return sourcePart([0, match.start])
+  if (marker === "'") return sourcePart([match.end, sourceLength])
+  if (marker.startsWith('<')) {
+    if (match.groups === undefined) return { text: token }
+    return sourcePart(match.groups[groupName])
+  }
+  let captureIndex = Number(marker)
+  let suffix = ''
+  if (captureIndex > match.captures.length && marker.length === 2) {
+    captureIndex = Number(marker[0])
+    suffix = marker[1]
+  }
+  if (captureIndex === 0 || captureIndex > match.captures.length) return { text: token }
+  return sourcePart(match.captures[captureIndex - 1], suffix)
+}
+
+function regexReplacements(edits, source, timeoutMs) {
+  if (edits.length === 0) return { error: 'regex_edits must contain at least one replacement' }
+  if (edits.length > EDIT_LIMITS.regexEdits) {
+    return { error: `regex_edits must contain at most ${EDIT_LIMITS.regexEdits} replacements` }
+  }
+  let matches = 0
+  let templateLength = 0
+  let expansionSteps = 0
+  const parsed = []
+  for (const [index, edit] of edits.entries()) {
+    if (edit === null || typeof edit !== 'object' || Array.isArray(edit)) {
+      return { error: `regex_edits[${index}] must be an object` }
+    }
+    const keys = Object.keys(edit)
+    if (keys.length !== 4 || !keys.includes('pattern') || !keys.includes('flags')
+      || !keys.includes('replacement') || !keys.includes('expected_matches')
+      || typeof edit.pattern !== 'string' || typeof edit.flags !== 'string'
+      || typeof edit.replacement !== 'string' || !Number.isSafeInteger(edit.expected_matches)) {
+      return { error: `regex_edits[${index}] expects exactly pattern, flags, replacement, and integer expected_matches` }
+    }
+    if (edit.pattern.length === 0) return { error: `regex_edits[${index}].pattern must be non-empty` }
+    if (!/^[gimsu]*$/.test(edit.flags) || new Set(edit.flags).size !== edit.flags.length) {
+      return { error: `regex_edits[${index}].flags must contain unique JavaScript g, i, m, s, or u flags` }
+    }
+    if (edit.expected_matches < 1 || edit.expected_matches > EDIT_LIMITS.regexMatches) {
+      return { error: `regex_edits[${index}].expected_matches must be between 1 and ${EDIT_LIMITS.regexMatches}` }
+    }
+    const parts = replacementParts(edit.replacement)
+    matches += edit.expected_matches
+    templateLength += edit.replacement.length
+    expansionSteps += edit.expected_matches * parts.length
+    if (matches > EDIT_LIMITS.regexMatches) {
+      return { error: `regex_edits must produce at most ${EDIT_LIMITS.regexMatches} matches in total` }
+    }
+    if (templateLength > EDIT_LIMITS.regexTemplateCodeUnits) {
+      return { error: `regex_edits replacement templates exceed the ${EDIT_LIMITS.regexTemplateCodeUnits} UTF-16 code-unit budget` }
+    }
+    if (expansionSteps > EDIT_LIMITS.regexExpansionSteps) {
+      return { error: `regex_edits exceed the ${EDIT_LIMITS.regexExpansionSteps} replacement-expansion step budget` }
+    }
+    parsed.push({
+      ...edit,
+      parts,
+    })
+  }
+  let result
+  try {
+    result = runInNewContext(REGEX_MATCH_SCRIPT, {
+      source,
+      rules: parsed.map(({ parts: _parts, ...rule }) => rule),
+      maxCaptureSlots: EDIT_LIMITS.regexCaptureSlots,
+    }, { timeout: timeoutMs })
+  } catch (error) {
+    return { error: `regex editing failed or exceeded its ${timeoutMs}ms matching budget: ${error.message}` }
+  }
+  if (result.error !== undefined) return result
+  return { replacements: result.replacements.map(match => ({
+    start: match.start,
+    end: match.end,
+    parts: parsed[match.ruleIndex].parts,
+    match,
+    index: match.ruleIndex,
+  })) }
+}
+
+function resolvedPartLength(part) {
+  return part.text === undefined ? part.end - part.start + part.suffix.length : part.text.length
+}
+
+function materializePart(part, source) {
+  return part.text === undefined ? source.slice(part.start, part.end) + part.suffix : part.text
+}
+
+function preflightAssembly(source, replacements) {
+  let generatedLength = source.length
+  let replacementLength = 0
+  const prepared = []
+  for (const replacement of replacements) {
+    const parts = replacement.text === undefined
+      ? replacement.parts.map(part => resolvePart(part, replacement.match, source.length))
+      : [{ text: replacement.text }]
+    let textLength = 0
+    for (const part of parts) {
+      textLength += resolvedPartLength(part)
+    }
+    replacementLength += textLength
+    generatedLength += textLength - (replacement.end - replacement.start)
+    prepared.push({ ...replacement, parts })
+  }
+  if (replacementLength > EDIT_LIMITS.generatedCodeUnits) {
+    return { error: `replacement output exceeds the ${EDIT_LIMITS.generatedCodeUnits} UTF-16 code-unit budget` }
+  }
+  if (generatedLength > EDIT_LIMITS.generatedCodeUnits) {
+    return { error: `edited source exceeds the ${EDIT_LIMITS.generatedCodeUnits} UTF-16 code-unit budget` }
+  }
+  return { replacements: prepared }
+}
+
+function assemble(source, replacements) {
+  const chunks = []
+  let cursor = 0
+  let changed = false
+  for (const replacement of replacements) {
+    const text = replacement.parts.map(part => materializePart(part, source)).join('')
+    chunks.push(source.slice(cursor, replacement.start), text)
+    cursor = replacement.end
+    if (text.length !== replacement.end - replacement.start
+      || !source.startsWith(text, replacement.start)) changed = true
+  }
+  chunks.push(source.slice(cursor))
+  return changed ? { code: chunks.join('') } : { error: 'edits must change at least one matched fragment' }
+}
+
+export function editRunCodeSchema() {
+  return {
+    name: 'edit_run_code',
+    description: 'Make a small exact or regular-expression change to the most recent eligible cell captured when this edit call is dispatched, then run the complete corrected cell. A successful edit becomes the next eligible cell. Use this only when replaying the whole cell is safe. If earlier code may already have caused an external effect, use a new run_code cell and its existing variables instead; this tool does not resume at the error location. Send exactly one atomic edits or regex_edits array. Choose edits for a few unique literal fragments; choose regex_edits when one counted pattern covers repeated fragments. Every resolved range must be non-overlapping in the original cell.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        edits: {
+          type: 'array', minItems: 1, maxItems: EDIT_LIMITS.exactEdits,
+          description: 'Atomic exact replacements, all resolved against the original target cell.',
+          items: {
+            type: 'object', additionalProperties: false,
+            properties: {
+              old_string: { type: 'string', minLength: 1, description: 'Exact text in the target cell. It must occur exactly once.' },
+              new_string: { type: 'string', description: 'Literal replacement text. Use an empty string to delete the match.' },
+            },
+            required: ['old_string', 'new_string'],
+          },
+        },
+        regex_edits: {
+          type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
+          description: 'Atomic regular-expression replacements, all matched against the original target cell.',
+          items: {
+            type: 'object', additionalProperties: false,
+            properties: {
+              pattern: { type: 'string', minLength: 1, description: 'JavaScript regular-expression source. Zero-length matches are rejected.' },
+              flags: { type: 'string', pattern: '^(?!.*(.).*\\1)[gimsu]*$', description: 'Unique JavaScript g, i, m, s, or u flags. Global matching is always applied.' },
+              replacement: { type: 'string', description: 'JavaScript replacement template, including capture references such as $1 or $<name>.' },
+              expected_matches: { type: 'integer', minimum: 1, maximum: EDIT_LIMITS.regexMatches, description: 'Exact match count required before any replacement is applied.' },
+            },
+            required: ['pattern', 'flags', 'replacement', 'expected_matches'],
+          },
+        },
+      },
+      oneOf: [{ required: ['edits'] }, { required: ['regex_edits'] }],
+    },
+  }
+}
+
+export function editRejectedCell(value, source, timeoutMs = DEFAULT_REGEX_TIMEOUT_MS) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return rejection('edit_run_code expects an object with exactly one edits or regex_edits array')
+  }
+  const keys = Object.keys(value)
+  if (keys.length !== 1 || !['edits', 'regex_edits'].includes(keys[0]) || !Array.isArray(value[keys[0]])) {
+    return rejection('edit_run_code expects exactly one edits or regex_edits array')
+  }
+  if (source === undefined) return rejection('no run_code cell is currently eligible for safe editing')
+  const resolved = keys[0] === 'edits'
+    ? exactReplacements(value.edits, source)
+    : regexReplacements(value.regex_edits, source, timeoutMs)
+  if (resolved.error !== undefined) return rejection(resolved.error)
+  const replacements = resolved.replacements.sort((left, right) => left.start - right.start)
+  for (let index = 1; index < replacements.length; index += 1) {
+    if (replacements[index].start < replacements[index - 1].end) {
+      return rejection(`${keys[0]}[${replacements[index].index}] overlaps ${keys[0]}[${replacements[index - 1].index}] in the target cell`)
+    }
+  }
+  const preflight = preflightAssembly(source, replacements)
+  if (preflight.error !== undefined) {
+    return rejection(keys[0] === 'regex_edits' ? preflight.error.replace(/^edits/, 'regex_edits') : preflight.error)
+  }
+  const assembled = assemble(source, preflight.replacements)
+  if (assembled.error !== undefined) {
+    return rejection(keys[0] === 'regex_edits' ? assembled.error.replace(/^edits/, 'regex_edits') : assembled.error)
+  }
+  return Object.freeze({
+    edited: true,
+    code: assembled.code,
+    description: keys[0] === 'edits'
+      ? EDIT_RUN_CODE_EXECUTION_DESCRIPTION
+      : REGEX_EDIT_RUN_CODE_EXECUTION_DESCRIPTION,
+  })
+}