blun-king-cli 9.1.536 → 9.1.550

package/bin/editable-tool-approval-policy.cjs

@@ -0,0 +1,540 @@
+'use strict';
+
+const {createHash} = require('node:crypto');
+
+const EDITABLE_TOOL_ALLOWLIST = Object.freeze([
+  'Bash',
+  'Read',
+  'Write',
+  'Edit',
+  'Glob',
+  'Grep',
+  'FetchURL',
+]);
+const EDITABLE_TOOL_ALLOWSET = new Set(EDITABLE_TOOL_ALLOWLIST);
+const DANGEROUS_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const APPROVAL_RESPONSE_FIELDS = new Set([
+  'decision',
+  'scope',
+  'feedback',
+  'selected_label',
+  'edited_tool_input',
+  'edited_tool_input_json',
+]);
+const DECISIONS = new Set(['approved', 'rejected', 'cancelled', 'edited']);
+const DEFAULT_LIMITS = Object.freeze({
+  maxBytes: 65_536,
+  maxDepth: 16,
+  maxProperties: 256,
+  maxCollectionItems: 512,
+  maxDecodedStringChars: 32_768,
+  maxChangedFields: 32,
+});
+
+class EditableToolApprovalError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'EditableToolApprovalError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new EditableToolApprovalError(code, message);
+}
+
+function resolveLimits(overrides = {}) {
+  if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    fail('EDITED_INPUT_LIMITS_INVALID', 'Edited input limits must be an object.');
+  }
+  const limits = {...DEFAULT_LIMITS};
+  for (const key of Object.keys(overrides)) {
+    if (!Object.hasOwn(DEFAULT_LIMITS, key)) {
+      fail('EDITED_INPUT_LIMITS_INVALID', `Unknown edited input limit: ${key}`);
+    }
+    const value = overrides[key];
+    if (!Number.isSafeInteger(value) || value < 0) {
+      fail('EDITED_INPUT_LIMITS_INVALID', `Edited input limit ${key} must be a non-negative safe integer.`);
+    }
+    if (value > DEFAULT_LIMITS[key]) {
+      fail('EDITED_INPUT_LIMIT_WIDENING_FORBIDDEN', `Edited input limit ${key} cannot exceed its production default.`);
+    }
+    limits[key] = value;
+  }
+  return limits;
+}
+
+function isEditableToolApprovalEligible(toolName) {
+  return typeof toolName === 'string' && EDITABLE_TOOL_ALLOWSET.has(toolName);
+}
+
+function validateUnicodeScalarString(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) {
+        fail('EDITED_INPUT_INVALID_UNICODE', 'Edited input contains an unpaired high surrogate.');
+      }
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      fail('EDITED_INPUT_INVALID_UNICODE', 'Edited input contains an unpaired low surrogate.');
+    }
+  }
+}
+
+function createCounters(limits) {
+  return {
+    limits,
+    properties: 0,
+    collectionItems: 0,
+    decodedStringChars: 0,
+  };
+}
+
+function countString(counters, value) {
+  validateUnicodeScalarString(value);
+  counters.decodedStringChars += value.length;
+  if (counters.decodedStringChars > counters.limits.maxDecodedStringChars) {
+    fail('EDITED_INPUT_STRING_LIMIT', 'Edited input exceeds the decoded string limit.');
+  }
+}
+
+function countProperty(counters) {
+  counters.properties += 1;
+  counters.collectionItems += 1;
+  if (counters.properties > counters.limits.maxProperties) {
+    fail('EDITED_INPUT_PROPERTIES_LIMIT', 'Edited input exceeds the property limit.');
+  }
+  if (counters.collectionItems > counters.limits.maxCollectionItems) {
+    fail('EDITED_INPUT_COLLECTION_LIMIT', 'Edited input exceeds the collection item limit.');
+  }
+}
+
+function countArrayItem(counters) {
+  counters.collectionItems += 1;
+  if (counters.collectionItems > counters.limits.maxCollectionItems) {
+    fail('EDITED_INPUT_COLLECTION_LIMIT', 'Edited input exceeds the collection item limit.');
+  }
+}
+
+function assertDepth(counters, depth) {
+  if (depth > counters.limits.maxDepth) {
+    fail('EDITED_INPUT_DEPTH_LIMIT', 'Edited input exceeds the nesting depth limit.');
+  }
+}
+
+function parseEditedToolInputJson(rawJson, limitOverrides) {
+  if (typeof rawJson !== 'string') {
+    fail('EDITED_INPUT_INVALID_JSON', 'Edited tool input must be supplied as JSON text.');
+  }
+  const limits = resolveLimits(limitOverrides);
+  if (Buffer.byteLength(rawJson, 'utf8') > limits.maxBytes) {
+    fail('EDITED_INPUT_BYTES_LIMIT', 'Edited input exceeds the raw byte limit.');
+  }
+
+  const counters = createCounters(limits);
+  let cursor = 0;
+
+  function skipWhitespace() {
+    while (cursor < rawJson.length && /[\u0009\u000a\u000d\u0020]/.test(rawJson[cursor])) cursor += 1;
+  }
+
+  function parseString() {
+    if (rawJson[cursor] !== '"') fail('EDITED_INPUT_INVALID_JSON', 'Expected a JSON string.');
+    cursor += 1;
+    let output = '';
+    while (cursor < rawJson.length) {
+      const char = rawJson[cursor];
+      cursor += 1;
+      if (char === '"') {
+        countString(counters, output);
+        return output;
+      }
+      if (char === '\\') {
+        if (cursor >= rawJson.length) fail('EDITED_INPUT_INVALID_JSON', 'Unterminated JSON escape.');
+        const escape = rawJson[cursor];
+        cursor += 1;
+        const simple = {'"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t'};
+        if (Object.hasOwn(simple, escape)) {
+          output += simple[escape];
+          continue;
+        }
+        if (escape !== 'u') fail('EDITED_INPUT_INVALID_JSON', 'Invalid JSON escape.');
+        const hex = rawJson.slice(cursor, cursor + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('EDITED_INPUT_INVALID_JSON', 'Invalid JSON Unicode escape.');
+        cursor += 4;
+        const code = Number.parseInt(hex, 16);
+        if (code >= 0xd800 && code <= 0xdbff) {
+          if (rawJson.slice(cursor, cursor + 2) !== '\\u') {
+            fail('EDITED_INPUT_INVALID_UNICODE', 'Unpaired high surrogate in JSON escape.');
+          }
+          const lowHex = rawJson.slice(cursor + 2, cursor + 6);
+          if (!/^[0-9a-fA-F]{4}$/.test(lowHex)) fail('EDITED_INPUT_INVALID_JSON', 'Invalid low surrogate escape.');
+          const low = Number.parseInt(lowHex, 16);
+          if (!(low >= 0xdc00 && low <= 0xdfff)) {
+            fail('EDITED_INPUT_INVALID_UNICODE', 'Unpaired high surrogate in JSON escape.');
+          }
+          cursor += 6;
+          output += String.fromCodePoint(0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00));
+        } else if (code >= 0xdc00 && code <= 0xdfff) {
+          fail('EDITED_INPUT_INVALID_UNICODE', 'Unpaired low surrogate in JSON escape.');
+        } else {
+          output += String.fromCharCode(code);
+        }
+        continue;
+      }
+      const code = char.charCodeAt(0);
+      if (code < 0x20) fail('EDITED_INPUT_INVALID_JSON', 'Unescaped control character in JSON string.');
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const next = rawJson.charCodeAt(cursor);
+        if (!(next >= 0xdc00 && next <= 0xdfff)) {
+          fail('EDITED_INPUT_INVALID_UNICODE', 'Unpaired high surrogate in JSON string.');
+        }
+        output += char + rawJson[cursor];
+        cursor += 1;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        fail('EDITED_INPUT_INVALID_UNICODE', 'Unpaired low surrogate in JSON string.');
+      } else {
+        output += char;
+      }
+    }
+    fail('EDITED_INPUT_INVALID_JSON', 'Unterminated JSON string.');
+  }
+
+  function parseNumber() {
+    const remainder = rawJson.slice(cursor);
+    const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(remainder);
+    if (!match) fail('EDITED_INPUT_INVALID_JSON', 'Invalid JSON number.');
+    cursor += match[0].length;
+    const value = Number(match[0]);
+    if (!Number.isFinite(value)) fail('EDITED_INPUT_NONFINITE_NUMBER', 'Edited input number must be finite.');
+    return value;
+  }
+
+  function parseArray(depth) {
+    assertDepth(counters, depth);
+    cursor += 1;
+    const output = [];
+    skipWhitespace();
+    if (rawJson[cursor] === ']') {
+      cursor += 1;
+      Object.setPrototypeOf(output, null);
+      return Object.freeze(output);
+    }
+    while (true) {
+      countArrayItem(counters);
+      output[output.length] = parseValue(depth + 1);
+      skipWhitespace();
+      if (rawJson[cursor] === ']') {
+        cursor += 1;
+        Object.setPrototypeOf(output, null);
+        return Object.freeze(output);
+      }
+      if (rawJson[cursor] !== ',') fail('EDITED_INPUT_INVALID_JSON', 'Expected comma or array end.');
+      cursor += 1;
+      skipWhitespace();
+    }
+  }
+
+  function parseObject(depth) {
+    assertDepth(counters, depth);
+    cursor += 1;
+    const output = Object.create(null);
+    const keys = new Set();
+    skipWhitespace();
+    if (rawJson[cursor] === '}') {
+      cursor += 1;
+      return Object.freeze(output);
+    }
+    while (true) {
+      if (rawJson[cursor] !== '"') fail('EDITED_INPUT_INVALID_JSON', 'Expected an object key.');
+      const key = parseString();
+      if (DANGEROUS_KEYS.has(key)) fail('EDITED_INPUT_DANGEROUS_KEY', `Dangerous edited input key: ${key}`);
+      if (keys.has(key)) fail('EDITED_INPUT_DUPLICATE_KEY', `Duplicate edited input key: ${key}`);
+      keys.add(key);
+      countProperty(counters);
+      skipWhitespace();
+      if (rawJson[cursor] !== ':') fail('EDITED_INPUT_INVALID_JSON', 'Expected colon after object key.');
+      cursor += 1;
+      output[key] = parseValue(depth + 1);
+      skipWhitespace();
+      if (rawJson[cursor] === '}') {
+        cursor += 1;
+        return Object.freeze(output);
+      }
+      if (rawJson[cursor] !== ',') fail('EDITED_INPUT_INVALID_JSON', 'Expected comma or object end.');
+      cursor += 1;
+      skipWhitespace();
+    }
+  }
+
+  function parseValue(depth) {
+    skipWhitespace();
+    const char = rawJson[cursor];
+    if (char === '{') return parseObject(depth);
+    if (char === '[') return parseArray(depth);
+    if (char === '"') return parseString();
+    if (char === '-' || (char >= '0' && char <= '9')) return parseNumber();
+    if (rawJson.startsWith('true', cursor)) {
+      cursor += 4;
+      return true;
+    }
+    if (rawJson.startsWith('false', cursor)) {
+      cursor += 5;
+      return false;
+    }
+    if (rawJson.startsWith('null', cursor)) {
+      cursor += 4;
+      return null;
+    }
+    fail('EDITED_INPUT_INVALID_JSON', 'Invalid JSON value.');
+  }
+
+  skipWhitespace();
+  const value = parseValue(1);
+  skipWhitespace();
+  if (cursor !== rawJson.length) fail('EDITED_INPUT_TRAILING_CONTENT', 'Edited input has trailing content.');
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    fail('EDITED_INPUT_OBJECT_REQUIRED', 'Edited tool input must be a top-level JSON object.');
+  }
+  return value;
+}
+
+function validateEditedToolInputObject(input, limitOverrides) {
+  const limits = resolveLimits(limitOverrides);
+  const counters = createCounters(limits);
+
+  function clone(value, depth) {
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+      countString(counters, value);
+      return value;
+    }
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) fail('EDITED_INPUT_NONFINITE_NUMBER', 'Edited input number must be finite.');
+      return value;
+    }
+    if (value === undefined) fail('EDITED_INPUT_UNDEFINED_REJECTED', 'Undefined is not valid edited JSON input.');
+    if (typeof value === 'function' || typeof value === 'bigint') {
+      fail('EDITED_INPUT_EXECUTABLE_REJECTED', 'Executable or non-JSON values are forbidden in edited input.');
+    }
+    if (typeof value === 'symbol') fail('EDITED_INPUT_SYMBOL_REJECTED', 'Symbols are forbidden in edited input.');
+
+    assertDepth(counters, depth);
+    const symbols = Object.getOwnPropertySymbols(value);
+    if (symbols.length > 0) fail('EDITED_INPUT_SYMBOL_REJECTED', 'Symbol keys are forbidden in edited input.');
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+
+    if (Array.isArray(value)) {
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Array.prototype && prototype !== null) {
+        fail('EDITED_INPUT_PROTOTYPE_REJECTED', 'Foreign array prototypes are forbidden in edited input.');
+      }
+      const output = [];
+      for (const key of Reflect.ownKeys(descriptors)) {
+        if (key === 'length') continue;
+        if (typeof key !== 'string' || !/^(?:0|[1-9]\d*)$/.test(key) || Number(key) >= value.length) {
+          fail('EDITED_INPUT_ARRAY_PROPERTY_REJECTED', 'Non-index array properties are forbidden in edited input.');
+        }
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = descriptors[String(index)];
+        if (!descriptor) fail('EDITED_INPUT_ARRAY_HOLE_REJECTED', 'Sparse arrays are forbidden in edited input.');
+        if (!Object.hasOwn(descriptor, 'value')) {
+          fail('EDITED_INPUT_ACCESSOR_REJECTED', 'Accessors are forbidden in edited input.');
+        }
+        countArrayItem(counters);
+        output[index] = clone(descriptor.value, depth + 1);
+      }
+      Object.setPrototypeOf(output, null);
+      return Object.freeze(output);
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      fail('EDITED_INPUT_PROTOTYPE_REJECTED', 'Foreign object prototypes are forbidden in edited input.');
+    }
+    const output = Object.create(null);
+    for (const key of Reflect.ownKeys(descriptors)) {
+      if (typeof key !== 'string') fail('EDITED_INPUT_SYMBOL_REJECTED', 'Symbol keys are forbidden in edited input.');
+      if (DANGEROUS_KEYS.has(key)) fail('EDITED_INPUT_DANGEROUS_KEY', `Dangerous edited input key: ${key}`);
+      const descriptor = descriptors[key];
+      if (!Object.hasOwn(descriptor, 'value')) {
+        fail('EDITED_INPUT_ACCESSOR_REJECTED', 'Accessors are forbidden in edited input.');
+      }
+      if (!descriptor.enumerable) {
+        fail('EDITED_INPUT_NONENUMERABLE_REJECTED', 'Non-enumerable properties are forbidden in edited input.');
+      }
+      countString(counters, key);
+      countProperty(counters);
+      output[key] = clone(descriptor.value, depth + 1);
+    }
+    return Object.freeze(output);
+  }
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    fail('EDITED_INPUT_OBJECT_REQUIRED', 'Edited tool input must be a top-level object.');
+  }
+  const output = clone(input, 1);
+  if (Buffer.byteLength(canonicalValueJson(output), 'utf8') > limits.maxBytes) {
+    fail('EDITED_INPUT_BYTES_LIMIT', 'Edited input exceeds the canonical byte limit.');
+  }
+  return output;
+}
+
+function readApprovalResponse(response) {
+  if (response === null || typeof response !== 'object' || Array.isArray(response)) {
+    fail('EDITED_APPROVAL_RESPONSE_INVALID', 'Approval response must be an object.');
+  }
+  const prototype = Object.getPrototypeOf(response);
+  if (prototype !== Object.prototype && prototype !== null) {
+    fail('EDITED_APPROVAL_RESPONSE_INVALID', 'Approval response must have a plain prototype.');
+  }
+  if (Object.getOwnPropertySymbols(response).length > 0) {
+    fail('EDITED_APPROVAL_UNKNOWN_FIELD', 'Approval response symbol fields are forbidden.');
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(response);
+  const values = Object.create(null);
+  for (const key of Object.keys(descriptors)) {
+    if (!APPROVAL_RESPONSE_FIELDS.has(key)) {
+      fail('EDITED_APPROVAL_UNKNOWN_FIELD', `Unknown approval response field: ${key}`);
+    }
+    const descriptor = descriptors[key];
+    if (!Object.hasOwn(descriptor, 'value')) {
+      fail('EDITED_APPROVAL_RESPONSE_INVALID', 'Approval response accessors are forbidden.');
+    }
+    values[key] = descriptor.value;
+  }
+  return {descriptors, values};
+}
+
+function validateEditedApprovalDecision({response, toolName, editCount, limits} = {}) {
+  const {descriptors, values} = readApprovalResponse(response);
+  if (!DECISIONS.has(values.decision)) {
+    fail('EDITED_APPROVAL_DECISION_INVALID', 'Unknown approval decision.');
+  }
+  if (!Number.isSafeInteger(editCount) || editCount < 0) {
+    fail('EDITED_APPROVAL_EDIT_COUNT_INVALID', 'Edit count must be a non-negative safe integer.');
+  }
+  const hasObjectInput = Object.hasOwn(descriptors, 'edited_tool_input');
+  const hasJsonInput = Object.hasOwn(descriptors, 'edited_tool_input_json');
+
+  if (values.decision !== 'edited') {
+    if (hasObjectInput || hasJsonInput) {
+      fail('EDITED_APPROVAL_INPUT_FORBIDDEN', 'Edited tool input is only valid for an edited decision.');
+    }
+    return Object.freeze({
+      decision: values.decision,
+      ...(Object.hasOwn(descriptors, 'scope') ? {scope: values.scope} : {}),
+      ...(Object.hasOwn(descriptors, 'feedback') ? {feedback: values.feedback} : {}),
+      ...(Object.hasOwn(descriptors, 'selected_label') ? {selectedLabel: values.selected_label} : {}),
+    });
+  }
+
+  if (!isEditableToolApprovalEligible(toolName)) {
+    fail('EDITED_APPROVAL_TOOL_INELIGIBLE', `Tool ${String(toolName)} does not allow edited approval.`);
+  }
+  if (editCount !== 0) fail('EDITED_APPROVAL_ALREADY_EDITED', 'A tool call may be edited at most once.');
+  if (Object.hasOwn(descriptors, 'scope')) {
+    fail('EDITED_APPROVAL_SCOPE_FORBIDDEN', 'Edited approval cannot create session scope.');
+  }
+  if (hasObjectInput === hasJsonInput) {
+    fail('EDITED_APPROVAL_INPUT_REQUIRED', 'Edited approval requires exactly one edited input representation.');
+  }
+  const editedToolInput = hasJsonInput
+    ? parseEditedToolInputJson(values.edited_tool_input_json, limits)
+    : validateEditedToolInputObject(values.edited_tool_input, limits);
+  return Object.freeze({decision: 'edited', editedToolInput});
+}
+
+function canonicalEditedToolInputJson(input) {
+  const safeInput = validateEditedToolInputObject(input);
+  function encode(value) {
+    if (value === null) return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') {
+      return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) return `[${Array.from(value, encode).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${encode(value[key])}`).join(',')}}`;
+  }
+  return encode(safeInput);
+}
+
+function hashEditedToolInput(input) {
+  return createHash('sha256').update(canonicalEditedToolInputJson(input), 'utf8').digest('hex');
+}
+
+function changedTopLevelFields(originalArgs, editedArgs) {
+  const keys = new Set([...Object.keys(originalArgs), ...Object.keys(editedArgs)]);
+  const changed = [];
+  for (const key of keys) {
+    const originalHas = Object.hasOwn(originalArgs, key);
+    const editedHas = Object.hasOwn(editedArgs, key);
+    if (originalHas !== editedHas) {
+      changed.push(key);
+      continue;
+    }
+    const originalValue = originalArgs[key];
+    const editedValue = editedArgs[key];
+    const originalJson = canonicalValueJson(originalValue);
+    const editedJson = canonicalValueJson(editedValue);
+    if (originalJson !== editedJson) changed.push(key);
+  }
+  return changed.sort();
+}
+
+function canonicalValueJson(value) {
+  if (value === null) return 'null';
+  if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${Array.from(value, canonicalValueJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalValueJson(value[key])}`).join(',')}}`;
+}
+
+function buildApprovalEditedEvent({
+  turnId,
+  toolCallId,
+  toolName,
+  originalArgs,
+  editedArgs,
+  maxChangedFields = DEFAULT_LIMITS.maxChangedFields,
+} = {}) {
+  if (!Number.isSafeInteger(turnId) || turnId < 0 || typeof toolCallId !== 'string' || toolCallId.length === 0 || toolCallId.length > 512) {
+    fail('EDITED_EVENT_IDENTITY_INVALID', 'Approval edited event identity is invalid.');
+  }
+  if (!isEditableToolApprovalEligible(toolName)) {
+    fail('EDITED_APPROVAL_TOOL_INELIGIBLE', `Tool ${String(toolName)} does not allow edited approval.`);
+  }
+  if (!Number.isSafeInteger(maxChangedFields) || maxChangedFields < 0 || maxChangedFields > DEFAULT_LIMITS.maxChangedFields) {
+    fail('EDITED_EVENT_CHANGED_FIELDS_LIMIT_INVALID', 'Changed-field limit is invalid.');
+  }
+  const safeOriginal = validateEditedToolInputObject(originalArgs);
+  const safeEdited = validateEditedToolInputObject(editedArgs);
+  const allChangedFields = changedTopLevelFields(safeOriginal, safeEdited);
+  const changedFields = Object.freeze(allChangedFields.slice(0, maxChangedFields));
+  return Object.freeze({
+    type: 'permission.approval_edited',
+    turnId,
+    toolCallId,
+    toolName,
+    originalArgsSha256: hashEditedToolInput(safeOriginal),
+    editedArgsSha256: hashEditedToolInput(safeEdited),
+    changedFields,
+    ...(allChangedFields.length > changedFields.length ? {changedFieldsTruncated: true} : {}),
+  });
+}
+
+module.exports = Object.freeze({
+  DEFAULT_LIMITS,
+  EDITABLE_TOOL_ALLOWLIST,
+  EditableToolApprovalError,
+  buildApprovalEditedEvent,
+  canonicalEditedToolInputJson,
+  hashEditedToolInput,
+  isEditableToolApprovalEligible,
+  parseEditedToolInputJson,
+  validateEditedApprovalDecision,
+  validateEditedToolInputObject,
+});

package/bin/editable-tool-approval-runtime.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+const {
+  canonicalEditedToolInputJson,
+  validateEditedToolInputObject,
+} = require('./editable-tool-approval-policy.cjs');
+
+class EditableToolReprepareError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'EditableToolReprepareError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new EditableToolReprepareError(code, message);
+}
+
+function buildEditedToolCallPlan({
+  step,
+  call,
+  editedArgs,
+  editCount,
+  preflightToolCall,
+} = {}) {
+  if (editCount !== 0) {
+    fail('EDITED_REPREPARE_ALREADY_EDITED', 'A tool call may be edited at most once.');
+  }
+  if (call?.kind !== 'runnable' || call.toolCall === null || typeof call.toolCall !== 'object' || typeof call.toolCall.id !== 'string' || typeof call.toolCall.name !== 'string') {
+    fail('EDITED_REPREPARE_CALL_INVALID', 'Only a runnable tool call can be re-prepared.');
+  }
+  if (!Array.isArray(step?.toolCalls) || typeof preflightToolCall !== 'function') {
+    fail('EDITED_REPREPARE_CONTEXT_INVALID', 'Edited re-preparation requires the active ordered tool-call list and preflight function.');
+  }
+
+  const matchingIndexes = [];
+  for (let index = 0; index < step.toolCalls.length; index += 1) {
+    if (step.toolCalls[index]?.id === call.toolCall.id) matchingIndexes.push(index);
+  }
+  if (matchingIndexes.length === 0) {
+    fail('EDITED_REPREPARE_IDENTITY_MISSING', 'The edited tool call is absent from the active ordered call list.');
+  }
+  if (matchingIndexes.length !== 1) {
+    fail('EDITED_REPREPARE_IDENTITY_AMBIGUOUS', 'The edited tool-call ID is not unique in the active call list.');
+  }
+  const position = matchingIndexes[0];
+  if (step.toolCalls[position] !== call.toolCall || call.toolName !== call.toolCall.name) {
+    fail('EDITED_REPREPARE_IDENTITY_CHANGED', 'The active tool-call identity changed before re-preparation.');
+  }
+
+  const safeEditedArgs = validateEditedToolInputObject(editedArgs);
+  const patchedToolCall = Object.freeze({
+    ...call.toolCall,
+    id: call.toolCall.id,
+    name: call.toolCall.name,
+    arguments: canonicalEditedToolInputJson(safeEditedArgs),
+  });
+  const patchedToolCalls = step.toolCalls.slice();
+  patchedToolCalls[position] = patchedToolCall;
+  const editedStep = {
+    ...step,
+    toolCalls: Object.freeze(patchedToolCalls),
+  };
+  const repreflight = preflightToolCall(editedStep, patchedToolCall);
+  if (repreflight === null || typeof repreflight !== 'object') {
+    fail('EDITED_REPREPARE_PREFLIGHT_INVALID', 'Edited tool preflight returned no result.');
+  }
+  if (repreflight.toolCall?.id !== call.toolCall.id || repreflight.toolCall?.name !== call.toolCall.name || repreflight.toolName !== call.toolName) {
+    fail('EDITED_REPREPARE_IDENTITY_CHANGED', 'Edited preflight changed the immutable tool identity.');
+  }
+  if (repreflight.kind === 'rejected') {
+    return Object.freeze({
+      kind: 'rejected',
+      step: editedStep,
+      call: repreflight,
+      editCount: 1,
+      output: repreflight.output,
+    });
+  }
+  if (repreflight.kind !== 'runnable') {
+    fail('EDITED_REPREPARE_PREFLIGHT_INVALID', 'Edited preflight returned an unsupported call state.');
+  }
+  if (repreflight.tool !== call.tool) {
+    fail('EDITED_REPREPARE_REGISTRY_CHANGED', 'The authoritative tool registry entry changed during edited approval.');
+  }
+  return Object.freeze({
+    kind: 'runnable',
+    step: editedStep,
+    call: repreflight,
+    editCount: 1,
+  });
+}
+
+module.exports = Object.freeze({
+  EditableToolReprepareError,
+  buildEditedToolCallPlan,
+});
+