@atelierai/uco 1.0.0

package/dist/server/rest/context.js

@@ -0,0 +1,194 @@
+/**
+ * Shared REST handler context — carries all server dependencies
+ * needed by route handlers.
+ */
+import { ToolCallControlError, } from '../../tool-call-control.js';
+/** Helper to send a JSON response with the correct content type. */
+export function sendJson(res, statusCode, body) {
+    res.statusCode = statusCode;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(normalizeHttpBody(statusCode, body)));
+}
+export function sendError(res, statusCode, code, message, retryable = statusCode >= 500, details) {
+    sendJson(res, statusCode, {
+        ok: false,
+        error: { code, message, retryable, ...(details === undefined ? {} : { details }) },
+    });
+}
+function normalizeHttpBody(statusCode, body) {
+    if (statusCode < 400 || body === null || typeof body !== 'object' || Array.isArray(body))
+        return body;
+    const record = body;
+    if (record['ok'] === false && record['error'] && typeof record['error'] === 'object')
+        return body;
+    if (typeof record['error'] !== 'string')
+        return body;
+    return {
+        ok: false,
+        error: {
+            code: `http-${statusCode}`,
+            message: record['error'],
+            // A handler may classify its failure explicitly (e.g. a tool-level
+            // execution failure is never transient); only fall back to the
+            // mechanical 5xx-is-retryable rule when it did not.
+            retryable: typeof record['retryable'] === 'boolean' ? record['retryable'] : statusCode >= 500,
+            ...(Object.keys(record).length > 1 ? { details: record } : {}),
+        },
+    };
+}
+/** Whether a REST body is the explicit `{ arguments, control }` form. */
+export function isExplicitToolCallWrapper(body) {
+    if (!isRecord(body))
+        return false;
+    // Once both wrapper members are present, treat the body as controlled so a
+    // malformed control cannot be reinterpreted as a legacy tool argument.
+    // A legacy body containing only `control` remains untouched.
+    return hasOwn(body, 'arguments') && hasOwn(body, 'control');
+}
+/**
+ * Send a stable controlled-call error. Legacy route failures continue to use
+ * the existing string-oriented `{ error: string }` path in their handlers.
+ */
+export function sendStructuredToolCallError(res, error, context, fallback = {}) {
+    const structured = structuredToolCallError(error, context, fallback);
+    sendJson(res, toolCallErrorStatus(structured.code), { ok: false, error: structured });
+}
+/** Build an abort signal that follows a REST caller while it is in flight. */
+export function createRestRequestSignal(req, res) {
+    const controller = new AbortController();
+    const abortIfOpen = () => {
+        if (!res.writableFinished)
+            controller.abort();
+    };
+    const onRequestAbort = () => controller.abort();
+    const onRequestClose = () => {
+        if (!req.complete)
+            controller.abort();
+    };
+    req.on('aborted', onRequestAbort);
+    req.on('close', onRequestClose);
+    res.on('close', abortIfOpen);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            req.off('aborted', onRequestAbort);
+            req.off('close', onRequestClose);
+            res.off('close', abortIfOpen);
+        },
+    };
+}
+function structuredToolCallError(error, context, fallback = {}) {
+    const candidate = error instanceof ToolCallControlError
+        ? error.toStructuredError()
+        : error && typeof error === 'object' && 'data' in error
+            ? error.data
+            : error;
+    // A structured error normally carries a stable `code`; a bare record with
+    // an actionable `message` (e.g. a merged diagnostic without a code) is
+    // accepted for the message while the code falls back to the default.
+    const value = isRecord(candidate)
+        && (typeof candidate.code === 'string'
+            || (typeof candidate.message === 'string' && candidate.message.trim().length > 0))
+        ? candidate
+        : undefined;
+    const code = value?.code ?? fallback.code ?? 'tool_execution_failed';
+    const message = value?.message
+        ?? fallback.message
+        ?? (typeof error === 'string' && error.trim().length > 0 ? error : undefined)
+        ?? safeErrorMessage(error);
+    const retryable = typeof value?.retryable === 'boolean'
+        ? value.retryable
+        : fallback.retryable ?? false;
+    const result = {
+        code: code,
+        message,
+        retryable,
+    };
+    const callId = value?.callId ?? fallback.callId ?? context?.callId;
+    const correlationId = value?.correlationId ?? fallback.correlationId ?? context?.correlationId;
+    if (callId !== undefined)
+        result.callId = callId;
+    if (correlationId !== undefined)
+        result.correlationId = correlationId;
+    const details = value?.details ?? fallback.details;
+    if (details !== undefined && isRecord(details))
+        result.details = details;
+    return result;
+}
+function toolCallErrorStatus(code) {
+    switch (code) {
+        case 'invalid_control':
+        case 'unsupported_control_version':
+        case 'path_policy_violation':
+        case 'validation_failed':
+            return 400;
+        case 'deadline_exceeded':
+        case 'cancelled':
+            return 408;
+        case 'middleware_rejected':
+        case 'confirmation_required':
+        case 'confirmation_invalid':
+        case 'confirmation_expired':
+        case 'confirmation_stale':
+        case 'undo_unavailable':
+        case 'identity_mismatch':
+        case 'identity_unavailable':
+            return 409;
+        case 'dry_run_unsupported':
+        case 'safety_unsupported':
+            return 422;
+        case 'authoring_transaction_failed':
+        case 'operation_interrupted':
+        case 'operation_owner_missing':
+            return 409;
+        case 'editor_not_ready':
+        case 'editor_settling':
+        case 'operation_capacity_exceeded':
+            return 503;
+        case 'operation_not_found':
+            return 404;
+        case 'cancellation_unavailable':
+            return 501;
+        case 'scheduling_metadata_invalid':
+            return 422;
+        default:
+            return 500;
+    }
+}
+function safeErrorMessage(error) {
+    return error instanceof ToolCallControlError ? error.message : 'Tool call failed.';
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Helper to send a plain text response. */
+export function sendText(res, statusCode, body, contentType = 'text/plain') {
+    res.statusCode = statusCode;
+    res.setHeader('Content-Type', contentType);
+    res.end(body);
+}
+/** Read and parse a JSON body from the request. Returns null for empty/non-JSON. */
+export function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('error', reject);
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (raw.length === 0) {
+                resolve(null);
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/server/rest/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/server/rest/context.ts"],"names":[],"mappings":"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"}

package/dist/server/rest/forward.d.ts

@@ -0,0 +1,66 @@
+/**
+ * REST→WebSocket forwarding helper.
+ *
+ * Sends an RPC request to the connected plugin over WebSocket and awaits the
+ * response via the pending tracker, with retry and deferred-completion support.
+ *
+ * @see design.md §D5 for the forwarding model.
+ */
+import type { ConnectionEntry, ConnectionRegistry } from '../ws/registry.js';
+import type { PendingTracker } from '../ws/pending.js';
+import type { McpHub } from '../ws/hub.js';
+import { type ToolCallContext } from '../../tool-call-control.js';
+export interface ForwardOptions {
+    /** The active session's instanceId pin (takes priority for routing). */
+    instanceId?: string | null;
+    /** Auth token for token-based routing. */
+    token?: string | null;
+    /** Timeout in ms (default 10s; 5min for tool calls). */
+    timeoutMs?: number;
+    /** Enable deferred completion (for RunCallTool / RunSystemTool). */
+    deferredRequestID?: string;
+    /** Override max retries (default 0). Honored only for an explicitly safe read. */
+    maxRetries?: number;
+    /** Explicit safe-read classification required before any forwarding retry. */
+    retrySafeRead?: boolean;
+    /** Caller cancellation signal for the local forwarding wait. */
+    signal?: AbortSignal;
+    /** Absolute deadline to bound every forwarding attempt. */
+    deadlineUnixMs?: number;
+    /** Normalized logical context used for controlled error correlation. */
+    context?: ToolCallContext;
+    /**
+     * Invoked with the connection entry whose response is being returned — the
+     * Editor identity that actually served the call. REST handlers use it to
+     * echo the served-identity tuple on matched constrained calls (COCli-01).
+     */
+    onServed?: (entry: ConnectionEntry) => void;
+    /**
+     * Invoked synchronously once the request has actually been sent to the
+     * plugin connection (COCli-09). Async REST callers wait for this before
+     * answering 202; pre-dispatch failures never fire it.
+     */
+    onDispatched?: () => void;
+}
+export interface ForwardDeps {
+    registry: ConnectionRegistry;
+    pending: PendingTracker;
+    hub: McpHub;
+    pluginTimeoutMs: number;
+}
+/**
+ * Forward an RPC call to the connected plugin and await the response.
+ *
+ * Retry behavior is opt-in. Automatic retries are disabled by default because tool calls
+ * can have side effects and because retrying would multiply the configured timeout.
+ */
+export declare function forwardToPlugin(deps: ForwardDeps, method: string, params: unknown, opts?: ForwardOptions): Promise<unknown>;
+/** Generate a unique requestID for tool calls (used in deferred completion). */
+export declare function generateRequestID(): string;
+/**
+ * The connection's full Editor identity tuple (bridge-identity-v1) — the same
+ * members the mismatch/unavailable errors report as `observed`, the readiness
+ * health connection block exposes, and a matched constrained call echoes as
+ * its `servedBy` tuple.
+ */
+export declare function identityTuple(entry: ConnectionEntry): Record<string, unknown>;

package/dist/server/rest/forward.js

@@ -0,0 +1,396 @@
+/**
+ * REST→WebSocket forwarding helper.
+ *
+ * Sends an RPC request to the connected plugin over WebSocket and awaits the
+ * response via the pending tracker, with retry and deferred-completion support.
+ *
+ * @see design.md §D5 for the forwarding model.
+ */
+import { extractDurableOperationId, makeRequest, } from '../ws/envelope.js';
+import { ErrorCode } from '../ws/envelope.js';
+import { DEFAULT_PLUGIN_TIMEOUT_MS, TOOL_CALL_TIMEOUT_MS, MAX_RETRIES, RETRY_DELAY_MS, ClientFacingMethod, } from '../types.js';
+import { createToolCallError, linkAbortSignals, } from '../../tool-call-control.js';
+let forwardIdCounter = 0;
+/**
+ * Forward an RPC call to the connected plugin and await the response.
+ *
+ * Retry behavior is opt-in. Automatic retries are disabled by default because tool calls
+ * can have side effects and because retrying would multiply the configured timeout.
+ */
+export async function forwardToPlugin(deps, method, params, opts) {
+    const { registry, pending, hub } = deps;
+    const maxRetries = opts?.retrySafeRead === true
+        ? (opts.maxRetries ?? MAX_RETRIES)
+        : 0;
+    const linkedSignals = linkAbortSignals(opts?.signal, opts?.context?.signal);
+    const callerSignal = linkedSignals.signal;
+    try {
+        const isToolCall = method === ClientFacingMethod.RunCallTool
+            || method === ClientFacingMethod.RunSystemTool;
+        // Preserve the historical five-minute budget for tool calls unless the
+        // caller explicitly supplies a timeout. Ordinary RPCs continue to use the
+        // server's configured plugin timeout.
+        const configuredTimeout = opts?.timeoutMs
+            ?? (isToolCall
+                ? TOOL_CALL_TIMEOUT_MS
+                : (deps.pluginTimeoutMs ?? DEFAULT_PLUGIN_TIMEOUT_MS));
+        const deadlineUnixMs = opts?.deadlineUnixMs ?? opts?.context?.deadlineUnixMs;
+        if (callerSignal?.aborted)
+            throw cancelledRpcError(opts?.context);
+        if (deadlineUnixMs !== undefined && deadlineUnixMs <= Date.now()) {
+            throw deadlineRpcError(opts?.context);
+        }
+        let lastError = null;
+        // Identity of the eligible connection that served the first attempt. A
+        // retry must never forward under a different generation than the original
+        // authority, so every later attempt is guarded against these.
+        let pinnedConnectionId;
+        let pinnedGeneration;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            if (callerSignal?.aborted)
+                throw cancelledRpcError(opts?.context);
+            const remainingMs = deadlineUnixMs === undefined
+                ? configuredTimeout
+                : Math.min(configuredTimeout, deadlineUnixMs - Date.now());
+            if (remainingMs <= 0)
+                throw deadlineRpcError(opts?.context);
+            const entry = registry.resolve({
+                instanceId: opts?.instanceId,
+                token: opts?.token,
+            });
+            if (!entry) {
+                lastError = {
+                    code: ErrorCode.PLUGIN_NOT_CONNECTED,
+                    message: 'No eligible plugin connection available (compatible handshake and tool registration required).',
+                };
+                // There is no destination to retry. A later REST request can use a
+                // connection once Unity has reconnected; holding this one open only
+                // turns a definitive state into an avoidable multi-second stall.
+                break;
+            }
+            if (attempt === 0) {
+                pinnedConnectionId = entry.connectionId;
+                pinnedGeneration = entry.generation;
+            }
+            else if (entry.connectionId !== pinnedConnectionId
+                || entry.generation !== pinnedGeneration) {
+                // The eligible connection changed between attempts. Retrying on the
+                // new generation would replay this call under the original authority
+                // across a generation boundary; surface the original failure instead.
+                break;
+            }
+            // Caller-asserted identity constraints are evaluated after connection
+            // resolution and before anything is forwarded: the wrong Editor must
+            // never receive the request, and an unavailable member must never pass.
+            enforceIdentityConstraints(entry, opts?.context);
+            const envelopeId = `r-${++forwardIdCounter}`;
+            const req = makeRequest(envelopeId, method, params);
+            // Start tracking the response.
+            const responsePromise = pending.track(envelopeId, remainingMs, method, entry.connectionId, {
+                signal: callerSignal,
+                abortError: cancelledRpcError(opts?.context),
+                requestID: opts?.deferredRequestID ?? opts?.context?.requestID,
+                callId: opts?.context?.callId,
+                cancellationId: opts?.context?.cancellationId,
+                generation: entry.generation,
+                onResolved: isToolCall && method === ClientFacingMethod.RunCallTool
+                    ? (result) => {
+                        const readiness = extractEditorReadiness(result);
+                        if (readiness)
+                            registry.updateEditorReadiness(entry.connectionId, readiness);
+                        if (extractDurableOperationId(result))
+                            registry.noteDurableOperationAccepted(entry.connectionId);
+                    }
+                    : undefined,
+                onAbortAfterDispatch: isToolCall && entry.capabilities?.has('cancel-tool-call-v1') === true
+                    ? (identity) => {
+                        hub.sendToConnection(entry.connectionId, makeRequest(`cancel-${++forwardIdCounter}`, ClientFacingMethod.CancelToolCall, {
+                            requestID: identity.requestID ?? '',
+                            callId: identity.callId ?? '',
+                            cancellationId: identity.cancellationId ?? '',
+                            generation: entry.generation ?? 0,
+                            reason: 'caller-aborted-in-flight-immediate-call',
+                        }));
+                    }
+                    : undefined,
+                // A regular plugin timeout remains a transport timeout when it fires
+                // before the absolute deadline. Only map the tracker timeout to a
+                // deadline error when that deadline is the controlling bound.
+                timeoutError: deadlineUnixMs !== undefined
+                    && deadlineUnixMs - Date.now() <= configuredTimeout
+                    ? deadlineRpcError(opts?.context)
+                    : undefined,
+            });
+            if (callerSignal?.aborted) {
+                return await responsePromise;
+            }
+            if (opts?.deferredRequestID) {
+                pending.trackDeferred(opts.deferredRequestID, envelopeId);
+            }
+            // Send the RPC to the plugin. No await occurs between the final abort
+            // check and this synchronous send decision, so pre-dispatch abort is zero-send.
+            const sent = hub.sendToConnection(entry.connectionId, req);
+            if (sent) {
+                pending.markDispatched(envelopeId);
+                // COCli-09: async REST callers wait only for dispatch (202) while the
+                // forward promise keeps updating the durable call record in the
+                // background.
+                opts?.onDispatched?.();
+            }
+            if (!sent) {
+                pending.reject(envelopeId, {
+                    code: ErrorCode.PLUGIN_NOT_CONNECTED,
+                    message: 'Failed to send to plugin (connection not open).',
+                });
+                lastError = {
+                    code: ErrorCode.PLUGIN_NOT_CONNECTED,
+                    message: 'Failed to send to plugin.',
+                };
+                if (attempt < maxRetries) {
+                    const delayMs = deadlineUnixMs === undefined
+                        ? RETRY_DELAY_MS
+                        : Math.min(RETRY_DELAY_MS, Math.max(0, deadlineUnixMs - Date.now()));
+                    if (delayMs <= 0)
+                        throw deadlineRpcError(opts?.context);
+                    const completed = await delay(delayMs, callerSignal);
+                    if (!completed) {
+                        if (callerSignal?.aborted)
+                            throw cancelledRpcError(opts?.context);
+                        throw deadlineRpcError(opts?.context);
+                    }
+                    continue;
+                }
+                break;
+            }
+            try {
+                const result = await responsePromise;
+                opts?.onServed?.(entry);
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                if (isControlError(lastError))
+                    throw lastError;
+                if (attempt < maxRetries) {
+                    const delayMs = deadlineUnixMs === undefined
+                        ? RETRY_DELAY_MS
+                        : Math.min(RETRY_DELAY_MS, Math.max(0, deadlineUnixMs - Date.now()));
+                    if (delayMs <= 0)
+                        throw deadlineRpcError(opts?.context);
+                    const completed = await delay(delayMs, callerSignal);
+                    if (!completed) {
+                        if (callerSignal?.aborted)
+                            throw cancelledRpcError(opts?.context);
+                        throw deadlineRpcError(opts?.context);
+                    }
+                    continue;
+                }
+                break;
+            }
+        }
+        throw lastError ?? { code: ErrorCode.INTERNAL_ERROR, message: 'Forwarding failed for unknown reason.' };
+    }
+    finally {
+        linkedSignals.dispose();
+    }
+}
+/** Generate a unique requestID for tool calls (used in deferred completion). */
+export function generateRequestID() {
+    return `t-${++forwardIdCounter}`;
+}
+function delay(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function cancelledRpcError(context) {
+    return {
+        code: ErrorCode.CALL_CANCELLED,
+        message: 'Tool call was cancelled by the caller.',
+        data: createToolCallError('cancelled', {
+            callId: context?.callId,
+            correlationId: context?.correlationId,
+        }),
+    };
+}
+function deadlineRpcError(context) {
+    return {
+        code: ErrorCode.CALL_DEADLINE_EXCEEDED,
+        message: 'Tool call deadline expired.',
+        data: createToolCallError('deadline_exceeded', {
+            callId: context?.callId,
+            correlationId: context?.correlationId,
+        }),
+    };
+}
+/**
+ * Evaluate caller-asserted identity constraints against the resolved
+ * connection's handshake identity. Paths compare case-insensitively on
+ * Windows; instance ids and PIDs compare exactly. Throws the structured,
+ * non-retryable rejection the CLI/REST surfaces translate into their
+ * identity-mismatch / identity-unavailable error codes.
+ */
+function enforceIdentityConstraints(entry, context) {
+    const constraints = context?.identity;
+    if (constraints === undefined)
+        return;
+    const violations = [];
+    const unavailable = [];
+    const identity = entry.identity;
+    if (constraints.instanceId !== undefined) {
+        const reported = entry.instanceId;
+        if (reported === undefined || reported === null) {
+            unavailable.push('expectedInstanceId');
+        }
+        else if (reported !== constraints.instanceId) {
+            violations.push({ field: 'expectedInstanceId', expected: constraints.instanceId, observed: reported });
+        }
+    }
+    if (constraints.projectPath !== undefined) {
+        const reported = identity?.projectPath;
+        if (reported === undefined) {
+            unavailable.push('expectedProjectPath');
+        }
+        else if (!pathsEqual(constraints.projectPath, reported)) {
+            violations.push({ field: 'expectedProjectPath', expected: constraints.projectPath, observed: reported });
+        }
+    }
+    if (constraints.pid !== undefined) {
+        const reported = identity?.editorPid;
+        if (reported === undefined) {
+            unavailable.push('expectedPid');
+        }
+        else if (reported !== constraints.pid) {
+            violations.push({ field: 'expectedPid', expected: constraints.pid, observed: reported });
+        }
+    }
+    if (violations.length === 0 && unavailable.length === 0)
+        return;
+    const observedTuple = identityTuple(entry);
+    if (unavailable.length > 0) {
+        throw {
+            code: ErrorCode.MIDDLEWARE_REJECTED,
+            message: `Connection ${entry.connectionId} did not report the asserted identity member(s): ${unavailable.join(', ')}. ` +
+                'A reachable server or successful ping never satisfies an identity constraint.',
+            data: createToolCallError('identity_unavailable', {
+                callId: context?.callId,
+                correlationId: context?.correlationId,
+                details: {
+                    unavailable,
+                    observed: observedTuple,
+                },
+            }),
+        };
+    }
+    throw {
+        code: ErrorCode.MIDDLEWARE_REJECTED,
+        message: `Routed Editor does not match the asserted identity constraints: ${violations
+            .map((violation) => `${violation.field} expected ${JSON.stringify(violation.expected)}, observed ${JSON.stringify(violation.observed)}`)
+            .join('; ')}.`,
+        data: createToolCallError('identity_mismatch', {
+            callId: context?.callId,
+            correlationId: context?.correlationId,
+            details: {
+                violations,
+                observed: observedTuple,
+            },
+        }),
+    };
+}
+/**
+ * The connection's full Editor identity tuple (bridge-identity-v1) — the same
+ * members the mismatch/unavailable errors report as `observed`, the readiness
+ * health connection block exposes, and a matched constrained call echoes as
+ * its `servedBy` tuple.
+ */
+export function identityTuple(entry) {
+    return {
+        instanceId: entry.instanceId ?? null,
+        projectPath: entry.identity?.projectPath ?? null,
+        editorPid: entry.identity?.editorPid ?? null,
+        unityVersion: entry.identity?.unityVersion ?? null,
+        generation: entry.generation,
+    };
+}
+function pathsEqual(expected, observed) {
+    if (expected === observed)
+        return true;
+    if (process.platform !== 'win32')
+        return false;
+    return expected.toLowerCase() === observed.toLowerCase();
+}
+function extractEditorReadiness(value) {
+    const queue = [value];
+    const seen = new Set();
+    for (let index = 0; index < queue.length && index < 32; index++) {
+        const current = queue[index];
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const record = current;
+        const readiness = record['readiness'] ?? record['Readiness'];
+        if (readiness && typeof readiness === 'object' && !Array.isArray(readiness))
+            return readiness;
+        for (const key of ['value', 'structuredContent', 'structured', 'result']) {
+            if (record[key] !== undefined)
+                queue.push(record[key]);
+        }
+    }
+    return undefined;
+}
+function isControlAbortError(error) {
+    const data = error.data;
+    return data?.code === 'cancelled'
+        || data?.code === 'deadline_exceeded'
+        || error.code === ErrorCode.CALL_CANCELLED
+        || error.code === ErrorCode.CALL_DEADLINE_EXCEEDED;
+}
+function isControlError(error) {
+    const data = error.data;
+    return isControlAbortError(error)
+        || data?.code === 'invalid_control'
+        || data?.code === 'unsupported_control_version'
+        || data?.code === 'middleware_rejected'
+        || data?.code === 'tool_execution_failed'
+        || data?.code === 'validation_failed'
+        || data?.code === 'confirmation_required'
+        || data?.code === 'confirmation_invalid'
+        || data?.code === 'confirmation_expired'
+        || data?.code === 'confirmation_stale'
+        || data?.code === 'dry_run_unsupported'
+        || data?.code === 'path_policy_violation'
+        || data?.code === 'safety_unsupported'
+        || data?.code === 'undo_unavailable'
+        || data?.code === 'authoring_transaction_failed'
+        || data?.code === 'editor_not_ready'
+        || data?.code === 'editor_settling'
+        || data?.code === 'operation_capacity_exceeded'
+        || data?.code === 'operation_not_found'
+        || data?.code === 'operation_owner_missing'
+        || data?.code === 'operation_interrupted'
+        || data?.code === 'cancellation_unavailable'
+        || data?.code === 'scheduling_metadata_invalid'
+        || data?.code === 'identity_mismatch'
+        || data?.code === 'identity_unavailable';
+}
+//# sourceMappingURL=forward.js.map