@atelierai/uco 1.0.0

package/dist/tool-call-control.js

@@ -0,0 +1,802 @@
+/**
+ * Transport-neutral tool-call control metadata.
+ *
+ * This module is deliberately independent from the HTTP and WebSocket
+ * adapters. Adapters can normalize a call once, carry the returned request
+ * across a hop, and use the runtime context without ever serializing its
+ * AbortSignal.
+ */
+export const TOOL_CALL_CONTROL_VERSION = 1;
+/** Alias retained for callers that prefer an explicit supported-version name. */
+export const SUPPORTED_TOOL_CALL_CONTROL_VERSION = TOOL_CALL_CONTROL_VERSION;
+const CONTROL_MEMBERS = new Set([
+    'version',
+    'callId',
+    'correlationId',
+    'parentCallId',
+    'deadlineUnixMs',
+    'cancellationId',
+    'idempotencyKey',
+    'confirm',
+    'dryRun',
+    'confirmation',
+    'expectedProjectPath',
+    'expectedInstanceId',
+    'expectedPid',
+]);
+const DEFAULT_ERROR_MESSAGES = {
+    invalid_control: 'Tool call control metadata is invalid.',
+    unsupported_control_version: 'Tool call control version is not supported.',
+    deadline_exceeded: 'Tool call deadline expired.',
+    cancelled: 'Tool call was cancelled.',
+    middleware_rejected: 'Tool call was rejected by middleware.',
+    tool_execution_failed: 'Tool execution failed.',
+    validation_failed: 'The authoring call did not pass validation.',
+    confirmation_required: 'A confirmation record is required for this tool call.',
+    confirmation_invalid: 'The confirmation plan is invalid.',
+    confirmation_expired: 'The confirmation plan has expired.',
+    confirmation_stale: 'The confirmation plan no longer matches this call.',
+    dry_run_unsupported: 'The requested dry-run mode is not supported by this tool.',
+    path_policy_violation: 'The requested path is not allowed by project policy.',
+    safety_unsupported: 'This tool call cannot be safely bound by the authoring policy.',
+    undo_unavailable: 'The requested Undo guarantee is unavailable.',
+    authoring_transaction_failed: 'The authoring transaction could not be completed safely.',
+    editor_not_ready: 'The selected Editor is not ready.',
+    editor_settling: 'The selected Editor generation is settling.',
+    operation_capacity_exceeded: 'Editor operation capacity is full.',
+    operation_not_found: 'The Editor operation was not found.',
+    operation_owner_missing: 'The Editor operation owner is unavailable.',
+    operation_interrupted: 'The Editor operation was interrupted.',
+    cancellation_unavailable: 'Cancellation propagation is unavailable.',
+    scheduling_metadata_invalid: 'Tool scheduling metadata is contradictory.',
+    identity_mismatch: 'The routed Editor does not match the asserted identity constraints.',
+    identity_unavailable: 'The routed connection did not report the asserted identity members.',
+};
+const NEVER_ABORTED_SIGNAL = new AbortController().signal;
+let generatedIdCounter = 0;
+/**
+ * Link all supplied caller/runtime signals without ever putting the derived
+ * signal on the wire.  A single signal is returned as-is; multiple signals
+ * share one controller and are detached by `dispose()` when the operation
+ * settles.
+ */
+export function linkAbortSignals(...signals) {
+    const unique = [];
+    for (const signal of signals) {
+        if (signal !== undefined && !unique.includes(signal))
+            unique.push(signal);
+    }
+    if (unique.length === 0)
+        return { signal: undefined, dispose: () => undefined };
+    if (unique.length === 1)
+        return { signal: unique[0], dispose: () => undefined };
+    const controller = new AbortController();
+    let disposed = false;
+    const onAbort = () => {
+        if (!disposed && !controller.signal.aborted)
+            controller.abort();
+    };
+    for (const signal of unique) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const signal of unique)
+                signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/**
+ * A safe, structured validation/control error. The error itself is useful to
+ * local callers while `toStructuredError()` is the machine contract for
+ * HTTP/WebSocket adapters.
+ */
+export class ToolCallControlError extends Error {
+    code;
+    retryable;
+    callId;
+    correlationId;
+    details;
+    cause;
+    constructor(code, message, options = {}) {
+        super(message ?? DEFAULT_ERROR_MESSAGES[code]);
+        this.name = 'ToolCallControlError';
+        this.code = code;
+        this.retryable = options.retryable ?? retryableForCode(code);
+        this.callId = options.callId;
+        this.correlationId = options.correlationId;
+        this.details = options.details;
+        this.cause = options.cause;
+    }
+    toStructuredError() {
+        const result = {
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+        };
+        if (this.callId !== undefined)
+            result.callId = this.callId;
+        if (this.correlationId !== undefined)
+            result.correlationId = this.correlationId;
+        if (this.details !== undefined)
+            result.details = this.details;
+        return result;
+    }
+    toJSON() {
+        return this.toStructuredError();
+    }
+}
+/** Build a structured error without exposing an underlying exception message. */
+export function createToolCallError(code, options = {}) {
+    return new ToolCallControlError(code, undefined, options).toStructuredError();
+}
+/** Convert a local control error to its stable wire value. */
+export function toStructuredToolCallError(error) {
+    if (error instanceof ToolCallControlError)
+        return error.toStructuredError();
+    return createToolCallError('tool_execution_failed');
+}
+/** Return true for errors created by this module, including cross-realm-like values. */
+export function isToolCallControlError(error) {
+    return error instanceof ToolCallControlError
+        || (isRecord(error) && typeof error.code === 'string' && error.name === 'ToolCallControlError');
+}
+/**
+ * Normalize a regular or system request. This function does not mutate the
+ * input and does not serialize the runtime signal.
+ */
+export function normalizeToolCall(request, options = {}) {
+    if (!isRecord(request)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call request must be an object.');
+    }
+    if (typeof request.name !== 'string' || request.name.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', 'Tool call name must be a non-empty string.');
+    }
+    if (!isRecord(request.arguments)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call arguments must be an object.');
+    }
+    const hasControl = hasOwn(request, 'control')
+        && request.control !== undefined
+        && request.control !== null;
+    if (!hasControl)
+        return normalizeLegacyToolCall(request, options);
+    if (!isRecord(request.control)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call control must be an object.');
+    }
+    return normalizeControlledToolCall(request, request.control, options);
+}
+/**
+ * Normalize either REST body form:
+ *
+ *   legacy:     { ...tool arguments }
+ *   controlled: { arguments: { ... }, control: { ... } }
+ *
+ * The wrapper is recognized only when both members are own object members.
+ * This keeps a legitimate legacy argument named `control` intact.
+ */
+export function normalizeRestToolCall(name, body, options = {}) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', 'Tool call name must be a non-empty string.');
+    }
+    const bodyObject = body === null || body === undefined ? {} : body;
+    if (!isRecord(bodyObject)) {
+        throw new ToolCallControlError('invalid_control', 'Request body must be a JSON object.');
+    }
+    const hasWrapperMembers = hasOwn(bodyObject, 'arguments') && hasOwn(bodyObject, 'control');
+    if (!hasWrapperMembers) {
+        return normalizeToolCall({ name, arguments: bodyObject }, options);
+    }
+    if (!isRecord(bodyObject.arguments) || !isRecord(bodyObject.control)) {
+        throw new ToolCallControlError('invalid_control', 'Controlled tool body requires object arguments and control members.');
+    }
+    const request = {
+        name,
+        arguments: bodyObject.arguments,
+        control: bodyObject.control,
+    };
+    if (hasOwn(bodyObject, 'requestID'))
+        request.requestID = bodyObject.requestID;
+    return normalizeToolCall(request, options);
+}
+/**
+ * Serialize a controlled REST body using the same canonical member ordering
+ * as the forwarding adapters. Unknown members are sorted after known ones.
+ */
+export function serializeControlledToolBody(arguments_, control, options = {}) {
+    if (!isRecord(arguments_)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call arguments must be an object.');
+    }
+    const input = isToolCallContext(control) ? contextAsControl(control) : control;
+    if (!isRecord(input)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call control must be an object.');
+    }
+    const normalized = normalizeControl(input, {
+        ...options,
+        fallbackRequestID: isToolCallContext(control) ? control.requestID : undefined,
+    });
+    const result = {
+        arguments: arguments_,
+        control: normalized.control,
+    };
+    if (normalized.context.requestID !== normalized.context.callId) {
+        result.requestID = normalized.context.requestID;
+    }
+    return result;
+}
+/**
+ * Normalize and serialize a named controlled call. This is the adapter seam
+ * shared by REST transports, library helpers, and command-facing adapters.
+ * Runtime signals are used for local cancellation only and never enter the
+ * returned body.
+ */
+export function serializeToolCallBody(name, arguments_, control, options = {}) {
+    const contextSignal = isToolCallContext(control) ? control.signal : undefined;
+    const requestID = options.requestID ?? (isToolCallContext(control) ? control.requestID : undefined);
+    const requestControl = isToolCallContext(control) ? contextAsControl(control) : control;
+    const request = { name, arguments: arguments_, control: requestControl };
+    if (requestID !== undefined)
+        request.requestID = requestID;
+    const normalized = normalizeToolCall(request, {
+        ...options,
+        signal: options.signal ?? contextSignal,
+    });
+    const body = serializeNormalizedToolCall(normalized);
+    return { body, request: normalized.request, context: normalized.context };
+}
+/** Serialize a previously normalized call without normalizing it again. */
+export function serializeNormalizedToolCall(normalized) {
+    if (normalized.context.legacy)
+        return { ...normalized.request.arguments };
+    const body = {
+        arguments: normalized.request.arguments,
+        control: normalized.request.control,
+    };
+    // The common controlled form derives requestID from callId. Keep a separate
+    // compatibility id only when the caller explicitly supplied one.
+    if (normalized.request.requestID !== normalized.context.callId) {
+        body.requestID = normalized.request.requestID;
+    }
+    return body;
+}
+/**
+ * Resolve an adapter's optional control/context fields into one value. Direct
+ * fields are useful to CLI adapters; an explicit `control` object remains the
+ * source of truth when it already contains the corresponding member.
+ */
+export function resolveToolCallControl(options) {
+    const base = options.control ?? options.context ?? undefined;
+    const hasDirect = hasValue(options.requestID)
+        || hasValue(options.callId)
+        || hasValue(options.correlationId)
+        || hasValue(options.parentCallId)
+        || hasValue(options.deadlineUnixMs)
+        || hasValue(options.cancellationId)
+        || hasValue(options.idempotencyKey)
+        || hasValue(options.controlVersion)
+        || hasValue(options.confirm)
+        || hasValue(options.dryRun)
+        || hasValue(options.confirmation)
+        || hasValue(options.expectedProjectPath)
+        || hasValue(options.expectedInstanceId)
+        || hasValue(options.expectedPid);
+    if (base !== undefined && !isRecord(base)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call control must be an object.');
+    }
+    // A legacy runtime context represents the absence of a wire control object.
+    // Keep it legacy unless the caller explicitly adds a control member.
+    if (base !== undefined && isToolCallContext(base) && base.legacy && !hasDirect)
+        return undefined;
+    if (!hasDirect)
+        return base;
+    const merged = base === undefined
+        ? {}
+        : isToolCallContext(base) ? contextAsControl(base) : { ...base };
+    if (hasValue(options.controlVersion))
+        merged.version = options.controlVersion;
+    if (hasValue(options.callId))
+        merged.callId = options.callId;
+    if (hasValue(options.correlationId))
+        merged.correlationId = options.correlationId;
+    if (hasValue(options.parentCallId))
+        merged.parentCallId = options.parentCallId;
+    if (hasValue(options.deadlineUnixMs))
+        merged.deadlineUnixMs = options.deadlineUnixMs;
+    if (hasValue(options.cancellationId))
+        merged.cancellationId = options.cancellationId;
+    if (hasValue(options.idempotencyKey))
+        merged.idempotencyKey = options.idempotencyKey;
+    if (hasValue(options.confirm))
+        merged.confirm = options.confirm;
+    if (hasValue(options.dryRun))
+        merged.dryRun = options.dryRun;
+    if (hasValue(options.confirmation))
+        merged.confirmation = options.confirmation;
+    if (hasValue(options.expectedProjectPath))
+        merged.expectedProjectPath = options.expectedProjectPath;
+    if (hasValue(options.expectedInstanceId))
+        merged.expectedInstanceId = options.expectedInstanceId;
+    if (hasValue(options.expectedPid))
+        merged.expectedPid = options.expectedPid;
+    return merged;
+}
+/** Serialize just the control envelope, omitting runtime-only members. */
+export function serializeToolCallControl(control, options = {}) {
+    return serializeControlledToolBody({}, control, options).control;
+}
+/**
+ * Derive a child context for an internal/batch invocation. A child always
+ * receives a new logical id, inherits the top-level correlation id, and never
+ * inherits its parent's idempotency key.
+ */
+export function deriveChildToolCallContext(parent, childControl = {}, options = {}) {
+    if (!isToolCallContext(parent)) {
+        throw new ToolCallControlError('invalid_control', 'Parent tool call context is invalid.');
+    }
+    if (!isRecord(childControl)) {
+        throw new ToolCallControlError('invalid_control', 'Child tool call control must be an object.');
+    }
+    // Validate the child version and known fields first. We then override the
+    // relationship fields that are owned by the parent/dispatcher.
+    const checked = normalizeControl(childControl, {
+        ...options,
+        fallbackRequestID: options.requestID,
+    });
+    let callId = checked.context.callId;
+    if (callId === parent.callId)
+        callId = generateFreshId(options, parent.callId);
+    const childDeadline = checked.context.deadlineUnixMs;
+    const deadlineUnixMs = minDeadline(parent.deadlineUnixMs, childDeadline);
+    const requestID = options.requestID ?? checked.context.requestID ?? callId;
+    validateRequiredId(requestID, 'requestID');
+    return withRuntimeSignal({
+        version: TOOL_CALL_CONTROL_VERSION,
+        requestID,
+        callId,
+        correlationId: parent.correlationId,
+        parentCallId: parent.callId,
+        deadlineUnixMs,
+        cancellationId: checked.context.cancellationId,
+        confirm: checked.context.confirm,
+        dryRun: checked.context.dryRun,
+        confirmation: checked.context.confirmation,
+        // A child executes within the same parent invocation, so it inherits the
+        // parent's Editor pin: routing a child to a different Editor would be
+        // exactly the wrong-Editor hazard the constraints exist to prevent.
+        identity: checked.context.identity ?? parent.identity,
+        // Idempotency is deliberately not inherited by children. An explicit
+        // child key remains valid and is preserved by the child normalizer.
+        idempotencyKey: checked.context.idempotencyKey,
+        legacy: false,
+        unknownMembers: { ...checked.context.unknownMembers },
+    }, options.signal ?? parent.signal);
+}
+/** Alias for callers that use the shorter context terminology. */
+export const deriveChildContext = deriveChildToolCallContext;
+/** Normalize a standalone control object into a runtime context. */
+export function normalizeToolCallContext(control, options = {}) {
+    if (!isRecord(control)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call control must be an object.');
+    }
+    return normalizeControl(control, {
+        ...options,
+        fallbackRequestID: options.requestID,
+    }).context;
+}
+/** Explicit aliases for adapters that name the operation after its input. */
+export const normalizeToolCallControl = normalizeToolCallContext;
+export const createToolCallContext = normalizeToolCallContext;
+function normalizeLegacyToolCall(request, options) {
+    const requestID = normalizeRequestID(request.requestID, options);
+    const requestWithoutControl = { ...request };
+    delete requestWithoutControl.control;
+    requestWithoutControl.requestID = requestID;
+    return {
+        request: requestWithoutControl,
+        context: withRuntimeSignal({
+            version: TOOL_CALL_CONTROL_VERSION,
+            requestID,
+            callId: requestID,
+            correlationId: requestID,
+            parentCallId: undefined,
+            deadlineUnixMs: undefined,
+            cancellationId: undefined,
+            idempotencyKey: undefined,
+            confirm: undefined,
+            dryRun: 'none',
+            confirmation: undefined,
+            legacy: true,
+            unknownMembers: {},
+        }, options.signal ?? NEVER_ABORTED_SIGNAL),
+    };
+}
+function normalizeControlledToolCall(request, control, options) {
+    const normalized = normalizeControl(control, {
+        ...options,
+        fallbackRequestID: request.requestID,
+    });
+    const normalizedRequest = { ...request, control: normalized.control };
+    normalizedRequest.requestID = normalized.context.requestID;
+    return { request: normalizedRequest, context: normalized.context };
+}
+function normalizeControl(control, options) {
+    const suppliedRequestID = normalizeOptionalRequestID(options.fallbackRequestID);
+    const suppliedCallId = normalizeOptionalId(control.callId, 'callId');
+    const callId = suppliedCallId ?? suppliedRequestID ?? generateId(options);
+    validateRequiredId(callId, 'callId');
+    const suppliedCorrelationId = normalizeOptionalId(control.correlationId, 'correlationId');
+    const correlationId = suppliedCorrelationId ?? callId;
+    validateRequiredId(correlationId, 'correlationId');
+    // Validate the version after extracting valid logical ids so a controlled
+    // future-version rejection remains correlated to the call that supplied it.
+    // No generated id is needed for the error path when the caller omitted ids.
+    const version = normalizeVersion(control.version, {
+        callId: suppliedCallId ?? suppliedRequestID,
+        correlationId: suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+    });
+    let parentCallId;
+    let deadlineUnixMs;
+    let cancellationId;
+    let idempotencyKey;
+    try {
+        parentCallId = normalizeOptionalId(control.parentCallId, 'parentCallId');
+        deadlineUnixMs = normalizeDeadline(control.deadlineUnixMs);
+        cancellationId = normalizeOpaqueString(control.cancellationId, 'cancellationId');
+        idempotencyKey = normalizeOpaqueString(control.idempotencyKey, 'idempotencyKey');
+    }
+    catch (error) {
+        if (error instanceof ToolCallControlError) {
+            throw new ToolCallControlError(error.code, error.message, {
+                callId: error.callId ?? suppliedCallId ?? suppliedRequestID,
+                correlationId: error.correlationId ?? suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+                details: error.details,
+                cause: error.cause,
+            });
+        }
+        throw error;
+    }
+    const requestID = suppliedRequestID ?? callId;
+    const unknownMembers = {};
+    for (const key of Object.keys(control)) {
+        if (!CONTROL_MEMBERS.has(key))
+            setOwn(unknownMembers, key, control[key]);
+    }
+    const identity = normalizeIdentityConstraints(control, {
+        callId: suppliedCallId ?? suppliedRequestID,
+        correlationId: suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+    });
+    const normalizedControl = {};
+    normalizedControl.version = version;
+    normalizedControl.callId = callId;
+    normalizedControl.correlationId = correlationId;
+    if (parentCallId !== undefined)
+        normalizedControl.parentCallId = parentCallId;
+    if (deadlineUnixMs !== undefined)
+        normalizedControl.deadlineUnixMs = deadlineUnixMs;
+    if (cancellationId !== undefined)
+        normalizedControl.cancellationId = cancellationId;
+    if (idempotencyKey !== undefined)
+        normalizedControl.idempotencyKey = idempotencyKey;
+    if (identity?.projectPath !== undefined)
+        normalizedControl.expectedProjectPath = identity.projectPath;
+    if (identity?.instanceId !== undefined)
+        normalizedControl.expectedInstanceId = identity.instanceId;
+    if (identity?.pid !== undefined)
+        normalizedControl.expectedPid = identity.pid;
+    const hasConfirm = hasOwn(control, 'confirm');
+    const confirm = normalizeConfirm(control.confirm, {
+        callId: suppliedCallId ?? suppliedRequestID,
+        correlationId: suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+    });
+    if (hasConfirm)
+        normalizedControl.confirm = confirm;
+    const hasDryRun = hasOwn(control, 'dryRun');
+    const dryRun = normalizeDryRun(control.dryRun, {
+        callId: suppliedCallId ?? suppliedRequestID,
+        correlationId: suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+    });
+    // Keep the legacy controlled wire shape compact when the directive was
+    // omitted; the runtime context still exposes the semantic `none` default.
+    if (hasDryRun)
+        normalizedControl.dryRun = dryRun;
+    const hasConfirmation = hasOwn(control, 'confirmation');
+    const confirmation = normalizeConfirmation(control.confirmation, {
+        callId: suppliedCallId ?? suppliedRequestID,
+        correlationId: suppliedCorrelationId ?? (suppliedCallId ?? suppliedRequestID),
+    });
+    if (hasConfirmation)
+        normalizedControl.confirmation = confirmation;
+    for (const key of Object.keys(unknownMembers).sort())
+        setOwn(normalizedControl, key, unknownMembers[key]);
+    return {
+        control: normalizedControl,
+        context: withRuntimeSignal({
+            version: TOOL_CALL_CONTROL_VERSION,
+            requestID,
+            callId,
+            correlationId,
+            parentCallId,
+            deadlineUnixMs,
+            cancellationId,
+            idempotencyKey,
+            confirm,
+            dryRun,
+            confirmation,
+            identity,
+            legacy: false,
+            unknownMembers,
+        }, options.signal ?? NEVER_ABORTED_SIGNAL),
+    };
+}
+const MAX_IDENTITY_PATH_LENGTH = 1024;
+const MAX_IDENTITY_ID_LENGTH = 160;
+/**
+ * Validate the three optional identity constraint members. Absent members stay
+ * absent; a present member must be well-formed so a typo fails fast with
+ * `invalid_control` instead of routing to (or refusing) the wrong Editor.
+ */
+function normalizeIdentityConstraints(control, ids) {
+    const projectPath = normalizeIdentityPath(control.expectedProjectPath, 'expectedProjectPath', ids);
+    const instanceId = normalizeIdentityId(control.expectedInstanceId, 'expectedInstanceId', ids);
+    const pid = normalizeIdentityPid(control.expectedPid, ids);
+    if (projectPath === undefined && instanceId === undefined && pid === undefined)
+        return undefined;
+    return {
+        ...(projectPath === undefined ? {} : { projectPath }),
+        ...(instanceId === undefined ? {} : { instanceId }),
+        ...(pid === undefined ? {} : { pid }),
+    };
+}
+function normalizeIdentityPath(value, member, ids) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', `${member} must be a non-empty string when supplied.`, ids);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > MAX_IDENTITY_PATH_LENGTH) {
+        throw new ToolCallControlError('invalid_control', `${member} must not exceed ${MAX_IDENTITY_PATH_LENGTH} characters.`, ids);
+    }
+    return trimmed;
+}
+function normalizeIdentityId(value, member, ids) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', `${member} must be a non-empty string when supplied.`, ids);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > MAX_IDENTITY_ID_LENGTH) {
+        throw new ToolCallControlError('invalid_control', `${member} must not exceed ${MAX_IDENTITY_ID_LENGTH} characters.`, ids);
+    }
+    return trimmed;
+}
+function normalizeIdentityPid(value, ids) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new ToolCallControlError('invalid_control', 'expectedPid must be a positive integer when supplied.', ids);
+    }
+    return value;
+}
+function normalizeVersion(value, ids = {}) {
+    if (value === undefined)
+        return TOOL_CALL_CONTROL_VERSION;
+    if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new ToolCallControlError('invalid_control', 'Tool call control version must be an integer.', {
+            callId: ids.callId,
+            correlationId: ids.correlationId,
+        });
+    }
+    if (value !== TOOL_CALL_CONTROL_VERSION) {
+        throw new ToolCallControlError('unsupported_control_version', undefined, {
+            callId: ids.callId,
+            correlationId: ids.correlationId,
+            details: { supportedVersion: TOOL_CALL_CONTROL_VERSION, receivedVersion: value },
+        });
+    }
+    return TOOL_CALL_CONTROL_VERSION;
+}
+function normalizeConfirm(value, ids) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new ToolCallControlError('invalid_control', 'confirm must be a boolean.', ids);
+    }
+    return value;
+}
+function normalizeDryRun(value, ids) {
+    if (value === undefined)
+        return 'none';
+    if (value !== 'none' && value !== 'validate' && value !== 'plan') {
+        throw new ToolCallControlError('invalid_control', 'dryRun must be one of: none, validate, plan.', ids);
+    }
+    return value;
+}
+function normalizeConfirmation(value, ids) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        throw new ToolCallControlError('invalid_control', 'confirmation must be an object.', ids);
+    }
+    if (typeof value.planId !== 'string' || value.planId.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', 'confirmation.planId must be a non-empty string.', ids);
+    }
+    if (typeof value.planHash !== 'string' || value.planHash.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', 'confirmation.planHash must be a non-empty string.', ids);
+    }
+    if (typeof value.expiresAtUnixMs !== 'number'
+        || !Number.isSafeInteger(value.expiresAtUnixMs)
+        || value.expiresAtUnixMs < 0) {
+        throw new ToolCallControlError('invalid_control', 'confirmation.expiresAtUnixMs must be a non-negative integer.', ids);
+    }
+    // Copy the token so normalizing a request never mutates a caller-owned
+    // object. Unknown members remain opaque and forward-compatible.
+    return { ...value, planId: value.planId, planHash: value.planHash, expiresAtUnixMs: value.expiresAtUnixMs };
+}
+function normalizeRequestID(value, options) {
+    if (value !== undefined && value !== null && typeof value !== 'string') {
+        throw new ToolCallControlError('invalid_control', 'requestID must be a string when supplied.');
+    }
+    if (typeof value === 'string' && value.trim().length > 0)
+        return value;
+    return generateId(options);
+}
+function normalizeOptionalRequestID(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new ToolCallControlError('invalid_control', 'requestID must be a string when supplied.');
+    }
+    if (value.length === 0)
+        return undefined;
+    if (value.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', 'requestID must be a non-empty string.');
+    }
+    return value;
+}
+function normalizeOptionalId(value, member) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', `${member} must be a non-empty string.`);
+    }
+    return value;
+}
+function validateRequiredId(value, member) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ToolCallControlError('invalid_control', `${member} must be a non-empty string.`);
+    }
+}
+function normalizeOpaqueString(value, member) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new ToolCallControlError('invalid_control', `${member} must be a string.`);
+    }
+    return value;
+}
+function normalizeDeadline(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new ToolCallControlError('invalid_control', 'deadlineUnixMs must be a non-negative integer.');
+    }
+    return value;
+}
+function minDeadline(parent, child) {
+    if (parent === undefined)
+        return child;
+    if (child === undefined)
+        return parent;
+    return Math.min(parent, child);
+}
+function generateId(options) {
+    const supplied = options.generateId?.();
+    if (supplied !== undefined) {
+        if (typeof supplied !== 'string' || supplied.trim().length === 0) {
+            throw new ToolCallControlError('invalid_control', 'Generated tool call id must be a non-empty string.');
+        }
+        return supplied;
+    }
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return `call-${globalThis.crypto.randomUUID()}`;
+    }
+    generatedIdCounter += 1;
+    return `call-${Date.now().toString(36)}-${generatedIdCounter.toString(36)}`;
+}
+function generateFreshId(options, existingId) {
+    const generated = generateId(options);
+    if (generated === existingId) {
+        throw new ToolCallControlError('invalid_control', 'Child call id must differ from its parent call id.');
+    }
+    return generated;
+}
+function contextAsControl(context) {
+    const control = {
+        ...context.unknownMembers,
+        version: context.version,
+        callId: context.callId,
+        correlationId: context.correlationId,
+        parentCallId: context.parentCallId,
+        deadlineUnixMs: context.deadlineUnixMs,
+        cancellationId: context.cancellationId,
+        idempotencyKey: context.idempotencyKey,
+        ...(context.confirm === undefined ? {} : { confirm: context.confirm }),
+        ...(context.dryRun === 'none' ? {} : { dryRun: context.dryRun }),
+        ...(context.confirmation === undefined ? {} : { confirmation: context.confirmation }),
+        ...(context.identity?.projectPath === undefined ? {} : { expectedProjectPath: context.identity.projectPath }),
+        ...(context.identity?.instanceId === undefined ? {} : { expectedInstanceId: context.identity.instanceId }),
+        ...(context.identity?.pid === undefined ? {} : { expectedPid: context.identity.pid }),
+    };
+    return control;
+}
+export function isToolCallContext(value) {
+    return isRecord(value)
+        && typeof value.callId === 'string'
+        && typeof value.correlationId === 'string'
+        && typeof value.requestID === 'string'
+        && typeof value.signal === 'object'
+        && typeof value.legacy === 'boolean'
+        && isRecord(value.unknownMembers);
+}
+function retryableForCode(_code) {
+    // A tool call can have side effects, so none of the initial failures is
+    // safe to replay implicitly. Callers may opt in explicitly per error.
+    return false;
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function hasValue(value) {
+    return value !== undefined && value !== null;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+    });
+}
+/** Keep runtime cancellation state out of JSON serialization. */
+function withRuntimeSignal(context, signal) {
+    Object.defineProperty(context, 'signal', {
+        configurable: true,
+        enumerable: true,
+        value: signal,
+        writable: false,
+    });
+    // Keep the runtime primitive visible to in-process middleware/tests while
+    // making accidental JSON serialization safe and deterministic.
+    Object.defineProperty(context, 'toJSON', {
+        configurable: true,
+        enumerable: false,
+        value: () => {
+            const serialized = { ...context };
+            delete serialized.signal;
+            return serialized;
+        },
+    });
+    Object.defineProperty(context, 'requestId', {
+        configurable: true,
+        enumerable: false,
+        get: () => context.requestID,
+    });
+    Object.defineProperty(context, 'abortSignal', {
+        configurable: true,
+        enumerable: false,
+        get: () => signal,
+    });
+    return context;
+}
+//# sourceMappingURL=tool-call-control.js.map