@debugg-ai/debugg-ai-mcp 4.3.0 → 4.4.0

package/dist/services/tunnel/protocol/codec.js

@@ -0,0 +1,327 @@
+/**
+ * Debugg tunnel wire protocol v1 — frame codec.
+ *
+ * Wire layout, one frame per websocket BINARY message:
+ *
+ *   offset 0, 1 byte : type (u8)
+ *   offset 1, 4 bytes: streamId (u32 big-endian)
+ *   offset 5, N bytes: payload
+ *
+ * The full table of types, payload shapes and rejection rules is on bead
+ * debugg_ai_mcp-xkoh.1.2, and pinned byte-for-byte by vectors/frames.json and
+ * vectors/invalid-frames.json.
+ *
+ * Pure and synchronous: no state, no IO, no timers, and no imports beyond this
+ * directory — the module is vendored verbatim into the tunnel server's repo.
+ */
+import { ProtocolError } from './errors.js';
+import { FrameType, HEADER_SIZE, MAX_DATA_PAYLOAD, MAX_ERROR_LENGTH, MAX_GOAWAY_REASON_BYTES, MAX_JSON_PAYLOAD, MAX_KIND_LENGTH, MAX_MARKER_LENGTH, MAX_PROBE_PATH_LENGTH, MAX_REQUEST_ID_LENGTH, MAX_STREAM_ID, MAX_WINDOW, } from './constants.js';
+const TYPE_NAME_BY_CODE = new Map(Object.entries(FrameType).map(([name, code]) => [code, name]));
+const MAX_U64 = (1n << 64n) - 1n;
+/** Strict: invalid UTF-8 is a protocol error, never a replacement character. */
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+function fail(detail) {
+    throw new ProtocolError(detail);
+}
+function requireStreamId(streamId, type) {
+    if (typeof streamId !== 'number' || !Number.isInteger(streamId) || streamId < 1 || streamId > MAX_STREAM_ID) {
+        fail(`${type}: stream id must be an integer in 1..${MAX_STREAM_ID}, got ${String(streamId)}`);
+    }
+    return streamId;
+}
+function requireSessionStreamId(streamId, type) {
+    if (streamId !== 0)
+        fail(`${type}: session frames use stream id 0, got ${String(streamId)}`);
+}
+function requireU16(value, type, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 0xffff) {
+        fail(`${type}: ${field} must be a u16, got ${String(value)}`);
+    }
+    return value;
+}
+function header(type, streamId, payloadLength) {
+    const buf = Buffer.allocUnsafe(HEADER_SIZE + payloadLength);
+    buf.writeUInt8(type, 0);
+    buf.writeUInt32BE(streamId >>> 0, 1);
+    return buf;
+}
+function encodeJsonPayload(obj, type) {
+    const payload = Buffer.from(JSON.stringify(obj), 'utf8');
+    if (payload.length > MAX_JSON_PAYLOAD) {
+        fail(`${type}: JSON payload is ${payload.length} bytes, limit is ${MAX_JSON_PAYLOAD}`);
+    }
+    return payload;
+}
+// ── JSON payload shapes ──────────────────────────────────────────────────────
+function checkOptionalString(value, maxLength, type, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        fail(`${type}: ${field} must be a string`);
+    if (value.length > maxLength)
+        fail(`${type}: ${field} is longer than ${maxLength} characters`);
+    return value;
+}
+/**
+ * Keep only the fields v1 defines, in spec order. Everything else is dropped —
+ * including anything address-shaped, which is what stops a server from ever
+ * telling a client where to dial.
+ */
+function normalizeMetadata(value) {
+    const kind = checkOptionalString(value.kind, MAX_KIND_LENGTH, 'OPEN', 'kind');
+    const requestId = checkOptionalString(value.requestId, MAX_REQUEST_ID_LENGTH, 'OPEN', 'requestId');
+    const metadata = {};
+    if (kind !== undefined)
+        metadata.kind = kind;
+    if (requestId !== undefined)
+        metadata.requestId = requestId;
+    return metadata;
+}
+function normalizeProbeRequest(value) {
+    const path = value.path;
+    if (typeof path !== 'string')
+        fail('PROBE: path is required and must be a string');
+    if (!path.startsWith('/'))
+        fail('PROBE: path must start with "/" — a probe can never be pointed elsewhere');
+    if (path.length > MAX_PROBE_PATH_LENGTH)
+        fail(`PROBE: path is longer than ${MAX_PROBE_PATH_LENGTH} characters`);
+    return { path };
+}
+function normalizeProbeResult(value) {
+    const { status, elapsedMs } = value;
+    if (status !== undefined) {
+        if (typeof status !== 'number' || !Number.isInteger(status) || status < 100 || status > 599) {
+            fail('PROBE_RESULT: status must be an integer in 100..599');
+        }
+    }
+    const marker = checkOptionalString(value.marker, MAX_MARKER_LENGTH, 'PROBE_RESULT', 'marker');
+    const error = checkOptionalString(value.error, MAX_ERROR_LENGTH, 'PROBE_RESULT', 'error');
+    if (typeof elapsedMs !== 'number' || !Number.isFinite(elapsedMs) || elapsedMs < 0) {
+        fail('PROBE_RESULT: elapsedMs is required and must be a finite number >= 0');
+    }
+    // Rebuilt in spec order (status, marker, error, elapsedMs) so the encoding is
+    // canonical whatever order the caller's object happened to use.
+    const out = { elapsedMs };
+    const ordered = {};
+    if (status !== undefined)
+        ordered.status = status;
+    if (marker !== undefined)
+        ordered.marker = marker;
+    if (error !== undefined)
+        ordered.error = error;
+    ordered.elapsedMs = out.elapsedMs;
+    return ordered;
+}
+function parseJsonObject(payload, type) {
+    if (payload.length === 0)
+        fail(`${type}: payload must be a JSON object`);
+    if (payload.length > MAX_JSON_PAYLOAD) {
+        fail(`${type}: JSON payload is ${payload.length} bytes, limit is ${MAX_JSON_PAYLOAD}`);
+    }
+    let text;
+    try {
+        text = utf8.decode(payload);
+    }
+    catch {
+        return fail(`${type}: payload is not valid UTF-8`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return fail(`${type}: payload is not valid JSON`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return fail(`${type}: payload must be a JSON object`);
+    }
+    return parsed;
+}
+// ── encode ───────────────────────────────────────────────────────────────────
+/**
+ * Encode one frame. Throws ProtocolError rather than emitting anything the peer
+ * would have to reject (oversized DATA, a zero WINDOW increment, streamId 0 on a
+ * stream frame, ...).
+ *
+ * JSON payloads are canonical: known fields only, in spec order, no whitespace.
+ */
+export function encodeFrame(frame) {
+    switch (frame.type) {
+        case 'OPEN': {
+            const streamId = requireStreamId(frame.streamId, 'OPEN');
+            const metadata = normalizeMetadata((frame.metadata ?? {}));
+            const ordered = {};
+            if (metadata.kind !== undefined)
+                ordered.kind = metadata.kind;
+            if (metadata.requestId !== undefined)
+                ordered.requestId = metadata.requestId;
+            const payload = encodeJsonPayload(ordered, 'OPEN');
+            const buf = header(FrameType.OPEN, streamId, payload.length);
+            payload.copy(buf, HEADER_SIZE);
+            return buf;
+        }
+        case 'DATA': {
+            const streamId = requireStreamId(frame.streamId, 'DATA');
+            const data = frame.data;
+            if (!data || data.length === 0)
+                fail('DATA: payload must be 1..' + MAX_DATA_PAYLOAD + ' bytes');
+            if (data.length > MAX_DATA_PAYLOAD) {
+                fail(`DATA: payload is ${data.length} bytes, limit is ${MAX_DATA_PAYLOAD}`);
+            }
+            const buf = header(FrameType.DATA, streamId, data.length);
+            Buffer.from(data.buffer, data.byteOffset, data.byteLength).copy(buf, HEADER_SIZE);
+            return buf;
+        }
+        case 'END':
+            return header(FrameType.END, requireStreamId(frame.streamId, 'END'), 0);
+        case 'RST': {
+            const streamId = requireStreamId(frame.streamId, 'RST');
+            const code = requireU16(frame.code, 'RST', 'code');
+            const buf = header(FrameType.RST, streamId, 2);
+            buf.writeUInt16BE(code, HEADER_SIZE);
+            return buf;
+        }
+        case 'WINDOW': {
+            const streamId = requireStreamId(frame.streamId, 'WINDOW');
+            const increment = frame.increment;
+            if (!Number.isInteger(increment) || increment < 1 || increment > MAX_WINDOW) {
+                fail(`WINDOW: increment must be an integer in 1..${MAX_WINDOW}, got ${String(increment)}`);
+            }
+            const buf = header(FrameType.WINDOW, streamId, 4);
+            buf.writeUInt32BE(increment, HEADER_SIZE);
+            return buf;
+        }
+        case 'PING':
+        case 'PONG': {
+            requireSessionStreamId(frame.streamId, frame.type);
+            const nonce = frame.nonce;
+            if (typeof nonce !== 'bigint' || nonce < 0n || nonce > MAX_U64) {
+                fail(`${frame.type}: nonce must be a u64`);
+            }
+            const buf = header(frame.type === 'PING' ? FrameType.PING : FrameType.PONG, 0, 8);
+            buf.writeBigUInt64BE(nonce, HEADER_SIZE);
+            return buf;
+        }
+        case 'GOAWAY': {
+            requireSessionStreamId(frame.streamId, 'GOAWAY');
+            const code = requireU16(frame.code, 'GOAWAY', 'code');
+            const reason = Buffer.from(frame.reason ?? '', 'utf8');
+            if (reason.length > MAX_GOAWAY_REASON_BYTES) {
+                fail(`GOAWAY: reason is ${reason.length} bytes, limit is ${MAX_GOAWAY_REASON_BYTES}`);
+            }
+            const buf = header(FrameType.GOAWAY, 0, 2 + reason.length);
+            buf.writeUInt16BE(code, HEADER_SIZE);
+            reason.copy(buf, HEADER_SIZE + 2);
+            return buf;
+        }
+        case 'PROBE': {
+            const probeId = requireStreamId(frame.streamId, 'PROBE');
+            const request = normalizeProbeRequest((frame.request ?? {}));
+            const payload = encodeJsonPayload({ path: request.path }, 'PROBE');
+            const buf = header(FrameType.PROBE, probeId, payload.length);
+            payload.copy(buf, HEADER_SIZE);
+            return buf;
+        }
+        case 'PROBE_RESULT': {
+            const probeId = requireStreamId(frame.streamId, 'PROBE_RESULT');
+            const result = normalizeProbeResult((frame.result ?? {}));
+            const payload = encodeJsonPayload(result, 'PROBE_RESULT');
+            const buf = header(FrameType.PROBE_RESULT, probeId, payload.length);
+            payload.copy(buf, HEADER_SIZE);
+            return buf;
+        }
+        default:
+            return fail(`unknown frame type ${String(frame.type)}`);
+    }
+}
+// ── decode ───────────────────────────────────────────────────────────────────
+/**
+ * Decode one websocket binary message into a frame.
+ *
+ * Throws ProtocolError for anything the spec rejects. Honours the view's
+ * byteOffset, because ws hands out Buffers backed by a shared pool.
+ */
+export function decodeFrame(bytes) {
+    if (bytes.length < HEADER_SIZE) {
+        fail(`frame is ${bytes.length} bytes, shorter than the ${HEADER_SIZE} byte header`);
+    }
+    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const type = buf.readUInt8(0);
+    const streamId = buf.readUInt32BE(1);
+    const payload = buf.subarray(HEADER_SIZE);
+    const name = TYPE_NAME_BY_CODE.get(type);
+    if (!name)
+        fail(`unknown frame type 0x${type.toString(16).padStart(2, '0')}`);
+    switch (name) {
+        case 'OPEN':
+            requireStreamId(streamId, 'OPEN');
+            return { type: 'OPEN', streamId, metadata: normalizeMetadata(parseJsonObject(payload, 'OPEN')) };
+        case 'DATA':
+            requireStreamId(streamId, 'DATA');
+            if (payload.length === 0)
+                fail('DATA: payload must be at least 1 byte');
+            if (payload.length > MAX_DATA_PAYLOAD) {
+                fail(`DATA: payload is ${payload.length} bytes, limit is ${MAX_DATA_PAYLOAD}`);
+            }
+            return { type: 'DATA', streamId, data: payload };
+        case 'END':
+            requireStreamId(streamId, 'END');
+            if (payload.length !== 0)
+                fail('END: carries no payload');
+            return { type: 'END', streamId };
+        case 'RST':
+            requireStreamId(streamId, 'RST');
+            if (payload.length !== 2)
+                fail(`RST: payload must be exactly 2 bytes, got ${payload.length}`);
+            return { type: 'RST', streamId, code: payload.readUInt16BE(0) };
+        case 'WINDOW': {
+            requireStreamId(streamId, 'WINDOW');
+            if (payload.length !== 4)
+                fail(`WINDOW: payload must be exactly 4 bytes, got ${payload.length}`);
+            const increment = payload.readUInt32BE(0);
+            if (increment < 1 || increment > MAX_WINDOW) {
+                fail(`WINDOW: increment must be in 1..${MAX_WINDOW}, got ${increment}`);
+            }
+            return { type: 'WINDOW', streamId, increment };
+        }
+        case 'PING':
+        case 'PONG':
+            requireSessionStreamId(streamId, name);
+            if (payload.length !== 8)
+                fail(`${name}: nonce must be exactly 8 bytes, got ${payload.length}`);
+            return { type: name, streamId: 0, nonce: payload.readBigUInt64BE(0) };
+        case 'GOAWAY': {
+            requireSessionStreamId(streamId, 'GOAWAY');
+            if (payload.length < 2)
+                fail('GOAWAY: payload starts with a u16 code');
+            const reasonBytes = payload.subarray(2);
+            if (reasonBytes.length > MAX_GOAWAY_REASON_BYTES) {
+                fail(`GOAWAY: reason is ${reasonBytes.length} bytes, limit is ${MAX_GOAWAY_REASON_BYTES}`);
+            }
+            let reason;
+            try {
+                reason = utf8.decode(reasonBytes);
+            }
+            catch {
+                return fail('GOAWAY: reason is not valid UTF-8');
+            }
+            return { type: 'GOAWAY', streamId: 0, code: payload.readUInt16BE(0), reason };
+        }
+        case 'PROBE':
+            requireStreamId(streamId, 'PROBE');
+            return { type: 'PROBE', streamId, request: normalizeProbeRequest(parseJsonObject(payload, 'PROBE')) };
+        case 'PROBE_RESULT':
+            requireStreamId(streamId, 'PROBE_RESULT');
+            return {
+                type: 'PROBE_RESULT',
+                streamId,
+                result: normalizeProbeResult(parseJsonObject(payload, 'PROBE_RESULT')),
+            };
+        default:
+            return fail(`unknown frame type ${String(name)}`);
+    }
+}
+/** Human-readable frame type name for a wire type byte, or undefined. */
+export function frameTypeName(typeCode) {
+    return TYPE_NAME_BY_CODE.get(typeCode);
+}

package/dist/services/tunnel/protocol/conformance.js

@@ -0,0 +1,171 @@
+/**
+ * Debugg tunnel wire protocol v1 — the conformance runner.
+ *
+ * The vectors in ./vectors are the specification. This runner is what makes them
+ * enforceable in a repo that is NOT this one: the tunnel server vendors this
+ * whole directory (bead debugg_ai_mcp-xkoh.1.6 §D/§G) and its CI calls
+ * runConformanceVectors on the copy. Without a checker inside the vendored unit,
+ * the server would have to hand-copy test files from __tests__, which is drift
+ * on day one — in the very mechanism meant to prevent drift.
+ *
+ * Deliberately dependency free and IO free: the CALLER reads the three JSON
+ * files and passes them in, so this works under any test runner, bundler or
+ * runtime. It returns failures instead of throwing, so each caller can report
+ * them its own way.
+ */
+import { decodeFrame, encodeFrame } from './codec.js';
+import { ProtocolError } from './errors.js';
+import { validateHandshakeRequest } from './handshake.js';
+import { ErrorCode } from './constants.js';
+function materialize(vector) {
+    if (typeof vector.hex === 'string')
+        return Buffer.from(vector.hex, 'hex');
+    const parts = [];
+    if (vector.hexPrefix)
+        parts.push(Buffer.from(vector.hexPrefix, 'hex'));
+    if (vector.fill)
+        parts.push(Buffer.alloc(vector.fill.count, Buffer.from(vector.fill.byte, 'hex')[0]));
+    if (vector.hexSuffix)
+        parts.push(Buffer.from(vector.hexSuffix, 'hex'));
+    return Buffer.concat(parts);
+}
+/** Vector JSON -> the Frame the codec works with. */
+function frameFromVector(v) {
+    switch (v.type) {
+        case 'OPEN':
+            return { type: 'OPEN', streamId: v.streamId, metadata: v.metadata };
+        case 'DATA':
+            return {
+                type: 'DATA',
+                streamId: v.streamId,
+                data: v.dataFill
+                    ? Buffer.alloc(v.dataFill.count, Buffer.from(v.dataFill.byte, 'hex')[0])
+                    : Buffer.from(v.dataHex, 'hex'),
+            };
+        case 'END':
+            return { type: 'END', streamId: v.streamId };
+        case 'RST':
+            return { type: 'RST', streamId: v.streamId, code: v.code };
+        case 'WINDOW':
+            return { type: 'WINDOW', streamId: v.streamId, increment: v.increment };
+        case 'PING':
+            return { type: 'PING', streamId: 0, nonce: BigInt(v.nonce) };
+        case 'PONG':
+            return { type: 'PONG', streamId: 0, nonce: BigInt(v.nonce) };
+        case 'GOAWAY':
+            return { type: 'GOAWAY', streamId: 0, code: v.code, reason: v.reason };
+        case 'PROBE':
+            return { type: 'PROBE', streamId: v.streamId, request: v.request };
+        case 'PROBE_RESULT':
+            return { type: 'PROBE_RESULT', streamId: v.streamId, result: v.result };
+        default:
+            throw new Error(`unknown vector frame type ${String(v.type)}`);
+    }
+}
+/** A Frame -> plain JSON, so a decoded frame can be compared with a vector. */
+function frameToComparable(frame) {
+    if (frame.type === 'DATA') {
+        return { type: 'DATA', streamId: frame.streamId, dataHex: Buffer.from(frame.data).toString('hex') };
+    }
+    if (frame.type === 'PING' || frame.type === 'PONG') {
+        return { type: frame.type, streamId: 0, nonce: frame.nonce.toString() };
+    }
+    return { ...frame };
+}
+function vectorToComparable(v) {
+    if (v.type === 'DATA' && v.dataFill) {
+        return {
+            type: 'DATA',
+            streamId: v.streamId,
+            dataHex: Buffer.alloc(v.dataFill.count, Buffer.from(v.dataFill.byte, 'hex')[0]).toString('hex'),
+        };
+    }
+    return { ...v };
+}
+/** Structural equality, ignoring key order and undefined-valued keys. */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null || typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    const left = a;
+    const right = b;
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    for (const key of keys) {
+        if (left[key] === undefined && right[key] === undefined)
+            continue;
+        if (!deepEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+function describe(value) {
+    return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? item.toString() : item));
+}
+/**
+ * Run every vector against this build of the codec and the handshake.
+ * An empty result means this copy of the module is on-spec.
+ */
+export function runConformanceVectors(vectors) {
+    const failures = [];
+    const fail = (file, vector, detail) => {
+        failures.push({ file, vector, detail });
+    };
+    for (const vector of (vectors.frames?.vectors ?? [])) {
+        const expectedBytes = materialize(vector);
+        if (!vector.decodeOnly) {
+            try {
+                const encoded = Buffer.from(encodeFrame(frameFromVector(vector.frame)));
+                if (!encoded.equals(expectedBytes)) {
+                    fail('frames.json', vector.name, `encoded ${encoded.length} bytes that do not match the vector (got ${encoded
+                        .subarray(0, 32)
+                        .toString('hex')}..., want ${expectedBytes.subarray(0, 32).toString('hex')}...)`);
+                }
+            }
+            catch (err) {
+                fail('frames.json', vector.name, `encode threw: ${err.message}`);
+            }
+        }
+        try {
+            const decoded = frameToComparable(decodeFrame(expectedBytes));
+            const expected = vectorToComparable(vector.frame);
+            if (!deepEqual(decoded, expected)) {
+                fail('frames.json', vector.name, `decoded ${describe(decoded)}, want ${describe(expected)}`);
+            }
+        }
+        catch (err) {
+            fail('frames.json', vector.name, `decode threw: ${err.message}`);
+        }
+    }
+    for (const vector of (vectors.invalidFrames?.vectors ?? [])) {
+        try {
+            decodeFrame(materialize(vector));
+            fail('invalid-frames.json', vector.name, 'decoded successfully; it must raise PROTOCOL_ERROR');
+        }
+        catch (err) {
+            if (!(err instanceof ProtocolError) || err.code !== ErrorCode.PROTOCOL_ERROR) {
+                fail('invalid-frames.json', vector.name, `raised ${err.name}, want ProtocolError`);
+            }
+        }
+    }
+    const handshakeDoc = vectors.handshake;
+    for (const vector of (handshakeDoc?.vectors ?? [])) {
+        try {
+            const result = validateHandshakeRequest(vector.requestHeaders, handshakeDoc.supported);
+            if (!deepEqual(result, vector.expect)) {
+                fail('handshake.json', vector.name, `returned ${describe(result)}, want ${describe(vector.expect)}`);
+            }
+        }
+        catch (err) {
+            fail('handshake.json', vector.name, `threw: ${err.message}`);
+        }
+    }
+    return failures;
+}

package/dist/services/tunnel/protocol/constants.js

@@ -0,0 +1,178 @@
+/**
+ * Debugg tunnel wire protocol v1 — constants.
+ *
+ * ONE source of truth for both sides of the wire: the MCP tunnel client in this
+ * repo and the debugg tunnel server in the debuggai-api stack. The full
+ * specification these values come from is recorded on bead
+ * debugg_ai_mcp-xkoh.1.2 (1.2 System Requirements), and the design context is
+ * docs/debugg-tunnel-server-design-2026-09-19.md §3.
+ *
+ * This file — and every other file under services/tunnel/protocol/ — imports
+ * nothing but node: built-ins. No logger, no config, no ws. The module has to
+ * stay embeddable in a service that is deployed from a different repo, and
+ * config/index.ts alone would drag DEBUGGAI_API_KEY validation into it.
+ */
+/** The only protocol version that exists today. */
+export const PROTOCOL_VERSION = 1;
+/** Versions this build can speak, best first. Sent in X-Debugg-Tunnel-Protocol. */
+export const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([1]);
+// ── Frame geometry ───────────────────────────────────────────────────────────
+/** type (u8) + streamId (u32 BE). */
+export const HEADER_SIZE = 5;
+/** Largest DATA payload in one frame. */
+export const MAX_DATA_PAYLOAD = 65536;
+/**
+ * Largest legal websocket message. Both ends set ws `maxPayload` to this, so an
+ * oversized message is refused by the ws layer (1009) before it is buffered.
+ */
+export const MAX_FRAME_SIZE = HEADER_SIZE + MAX_DATA_PAYLOAD;
+/** Largest JSON payload (OPEN / PROBE / PROBE_RESULT). */
+export const MAX_JSON_PAYLOAD = 16384;
+/** Largest GOAWAY reason, in UTF-8 bytes (the u16 code is not counted). */
+export const MAX_GOAWAY_REASON_BYTES = 1024;
+/** Largest PROBE path. */
+export const MAX_PROBE_PATH_LENGTH = 2048;
+/** Largest OPEN `requestId`. */
+export const MAX_REQUEST_ID_LENGTH = 128;
+/** Largest OPEN `kind`. */
+export const MAX_KIND_LENGTH = 32;
+/** Largest PROBE_RESULT `marker`. */
+export const MAX_MARKER_LENGTH = 64;
+/** Largest PROBE_RESULT `error`. */
+export const MAX_ERROR_LENGTH = 256;
+// ── Streams ──────────────────────────────────────────────────────────────────
+/** streamId 0 is reserved for session-level frames (PING/PONG/GOAWAY). */
+export const SESSION_STREAM_ID = 0;
+/** Highest u32 stream id. Reaching it means GOAWAY + reconnect. */
+export const MAX_STREAM_ID = 0xffffffff;
+/**
+ * Concurrent streams per tunnel. One Next.js dev page has been measured at 54
+ * requests, and nginx deliberately has no upstream keepalive for the tunnel, so
+ * one browser request is one stream.
+ */
+export const MAX_CONCURRENT_STREAMS = 256;
+// ── Flow control ─────────────────────────────────────────────────────────────
+/** Credit each stream direction starts with. Fixed in v1, not negotiated. */
+export const INITIAL_WINDOW = 262144;
+/** A window may never exceed this after a WINDOW increment. */
+export const MAX_WINDOW = 2147483647;
+/**
+ * Receiver policy (pinned by tests, not by the wire): announce consumed bytes
+ * once this many are un-announced, so the sender never stalls while three
+ * quarters of the window is still in flight.
+ */
+export const WINDOW_UPDATE_THRESHOLD = 65536;
+/**
+ * Send-side bound: the session hands frames to the socket only while fewer than
+ * this many bytes are un-acked (ws send callback still pending), so a peer that
+ * stops reading cannot inflate the websocket's own send buffer.
+ */
+export const MAX_UNACKED_SEND_BYTES = 262144;
+// ── Timers ───────────────────────────────────────────────────────────────────
+/** PING cadence. Under the public ALB's idle_timeout of 60s. */
+export const PING_INTERVAL_MS = 20000;
+/** No frame of any type for this long means the peer is dead. */
+export const DEAD_PEER_TIMEOUT_MS = 60000;
+/** Client-side PROBE deadline. Matches TunnelHealthProbeOptions.timeoutMs today. */
+export const PROBE_TIMEOUT_MS = 5000;
+/**
+ * Normative for the tunnel server: how long a browser request is held while the
+ * tunnel's client is reconnecting, before DEBUGG_TUNNEL_OFFLINE is rendered.
+ */
+export const RECONNECT_GRACE_MS = 5000;
+// ── Frame types ──────────────────────────────────────────────────────────────
+export const FrameType = Object.freeze({
+    OPEN: 0x01,
+    DATA: 0x02,
+    END: 0x03,
+    RST: 0x04,
+    WINDOW: 0x05,
+    PING: 0x06,
+    PONG: 0x07,
+    GOAWAY: 0x08,
+    PROBE: 0x09,
+    PROBE_RESULT: 0x0a,
+});
+// ── Error codes (RST payload, GOAWAY payload, and websocket close 4000+code) ──
+export const ErrorCode = Object.freeze({
+    /** Stream was NOT processed — cap reached, or OPEN after GOAWAY. Retryable. */
+    REFUSED: 1,
+    /** Stream aborted by an endpoint. */
+    RESET: 2,
+    /** A deadline expired (dead peer, drain deadline). */
+    TIMEOUT: 3,
+    /** The peer violated the spec. */
+    PROTOCOL_ERROR: 4,
+    /** Sender is shutting down; reconnect. */
+    GOING_AWAY: 5,
+    /** Client could not dial its local target -> DEBUGG_TUNNEL_UPSTREAM_REFUSED. */
+    UPSTREAM_UNREACHABLE: 6,
+    /** Tunnel revoked or past its max lifetime. Do not reconnect with this token. */
+    REVOKED: 7,
+});
+/** Websocket close codes. Anything other than a drained close is 4000 + ErrorCode. */
+export const CloseCode = Object.freeze({
+    NORMAL: 1000,
+    /** RFC 6455: the connection dropped without a close frame. Never sent, only observed. */
+    ABNORMAL: 1006,
+    REFUSED: 4001,
+    RESET: 4002,
+    TIMEOUT: 4003,
+    PROTOCOL_ERROR: 4004,
+    GOING_AWAY: 4005,
+    UPSTREAM_UNREACHABLE: 4006,
+    REVOKED: 4007,
+});
+/** Close code carrying a protocol error code. */
+export const CLOSE_CODE_BASE = 4000;
+// ── Handshake ────────────────────────────────────────────────────────────────
+/**
+ * Header names, lowercase, because that is how node hands them to a server
+ * (http.IncomingMessage.headers). The canonical spellings a client sends are in
+ * REQUEST_HEADER_NAMES.
+ */
+export const Header = Object.freeze({
+    AUTHORIZATION: 'authorization',
+    TUNNEL_ID: 'x-debugg-tunnel-id',
+    PROTOCOL: 'x-debugg-tunnel-protocol',
+    CLIENT_VERSION: 'x-debugg-tunnel-client-version',
+    SUPPORTED: 'x-debugg-tunnel-supported',
+    /** Response header on the server's error pages, alongside the body marker. */
+    TUNNEL_ERROR: 'x-debugg-tunnel-error',
+});
+export const RequestHeader = Object.freeze({
+    AUTHORIZATION: 'Authorization',
+    TUNNEL_ID: 'X-Debugg-Tunnel-Id',
+    PROTOCOL: 'X-Debugg-Tunnel-Protocol',
+    CLIENT_VERSION: 'X-Debugg-Tunnel-Client-Version',
+    SUPPORTED: 'X-Debugg-Tunnel-Supported',
+});
+/** A tunnel id has to be a DNS label: it becomes `<id>.tunnel.debugg.ai`. */
+export const TUNNEL_ID_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Handshake rejection statuses. */
+export const HandshakeStatus = Object.freeze({
+    SWITCHING_PROTOCOLS: 101,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    UPGRADE_REQUIRED: 426,
+});
+export const HandshakeError = Object.freeze({
+    UNSUPPORTED_PROTOCOL_VERSION: 'UNSUPPORTED_PROTOCOL_VERSION',
+    BAD_TUNNEL_ID: 'BAD_TUNNEL_ID',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+});
+// ── Server error markers (server emits, client parses) ───────────────────────
+export const TunnelErrorMarker = Object.freeze({
+    /** No client connected — the ERR_NGROK_3200 analogue. */
+    OFFLINE: 'DEBUGG_TUNNEL_OFFLINE',
+    /** Unknown or revoked tunnel id. */
+    UNKNOWN: 'DEBUGG_TUNNEL_UNKNOWN',
+    /** The client could not dial the local app — the ERR_NGROK_8012 analogue. */
+    UPSTREAM_REFUSED: 'DEBUGG_TUNNEL_UPSTREAM_REFUSED',
+});
+/** HTTP status each marker is served with, chosen to match the ngrok codes they replace. */
+export const MARKER_HTTP_STATUS = Object.freeze({
+    [TunnelErrorMarker.OFFLINE]: 404,
+    [TunnelErrorMarker.UNKNOWN]: 404,
+    [TunnelErrorMarker.UPSTREAM_REFUSED]: 502,
+});