unreal-mcp-proxy 0.1.0

package/dist/session-model.js

@@ -0,0 +1,270 @@
+function requestLabel(body) {
+    const shape = (body && typeof body === "object" && !Array.isArray(body) ? body : {});
+    if (!body || shape.omitted)
+        return { title: "MCP request", category: "transport" };
+    if (shape.method === "initialize")
+        return { title: "MCP initialize", category: "connection" };
+    if (shape.method === "notifications/initialized")
+        return { title: "MCP initialized", category: "connection" };
+    if (shape.method === "tools/list")
+        return { title: "List tools", category: "discovery" };
+    if (shape.method !== "tools/call")
+        return { title: shape.method ?? "MCP request", category: "transport" };
+    const name = shape.params?.name ?? "unknown tool";
+    const args = shape.params?.arguments ?? {};
+    if (name === "list_toolsets" || name === "describe_toolset") {
+        return {
+            title: name === "list_toolsets" ? "List Unreal toolsets" : "Describe Unreal toolset",
+            category: "discovery", toolName: name, arguments: args
+        };
+    }
+    if (name === "call_tool") {
+        // Epic's Unreal MCP wraps every engine tool behind call_tool(toolset_name, tool_name, arguments)
+        const toolsetName = typeof args.toolset_name === "string" ? args.toolset_name : undefined;
+        const toolName = typeof args.tool_name === "string" ? args.tool_name : undefined;
+        const toolset = toolsetName ? toolsetName.split(".").at(-1) : "TopLevel";
+        return {
+            title: `${toolset}.${toolName ?? "unknown"}`,
+            subtitle: toolsetName,
+            category: "unreal_tool",
+            toolName,
+            toolsetName,
+            arguments: (args.arguments ?? {})
+        };
+    }
+    return { title: name, category: "mcp_tool", toolName: name, arguments: args };
+}
+function responseError(body, status) {
+    if (status != null && status >= 400)
+        return `HTTP ${status}`;
+    const record = body && typeof body === "object" && !Array.isArray(body) ? body : null;
+    const messages = record?.transport === "sse" ? (record.events ?? []) : [body];
+    for (const message of messages) {
+        const shape = (message ?? {});
+        if (shape.error)
+            return shape.error.message ?? "MCP error";
+        if (shape.result?.isError)
+            return "Tool returned an error";
+        const content = shape.result?.content;
+        if (Array.isArray(content)) {
+            const text = content.map((item) => item?.text ?? "").join("\n");
+            if (/^(error|failed|exception|timeout)\s*:/i.test(text.trim()))
+                return text.slice(0, 300);
+        }
+    }
+    return null;
+}
+const round = (value) => Math.round((value ?? 0) * 100) / 100;
+function median(values) {
+    if (!values.length)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function timing(event) {
+    const total = event.durationMs ?? 0;
+    const headers = Math.min(total, event.responseHeadersMs ?? total);
+    const result = Math.min(total, event.resultEventMs ?? total);
+    return {
+        requestToHeadersMs: round(headers),
+        toolResultMs: round(Math.max(0, result - headers)),
+        proxyFinalizeMs: round(Math.max(0, total - result)),
+        completionReason: event.completionReason ?? "stream_end"
+    };
+}
+function targetNode(call) {
+    const actor = call.arguments?.actor;
+    const refPath = actor && typeof actor === "object" && !Array.isArray(actor)
+        ? actor.refPath : undefined;
+    if (typeof refPath === "string" && call.toolName === "get_actor_transform") {
+        return { key: `actor:${refPath}`, label: refPath.split(/[.:]/).at(-1) ?? refPath, subtitle: call.toolName, kind: "target" };
+    }
+    return {
+        key: `tool:${call.toolsetName ?? call.category}:${call.toolName ?? call.title}`,
+        label: call.toolName ?? call.title,
+        subtitle: call.toolsetName ?? call.category,
+        kind: "tool"
+    };
+}
+function buildFlowGraph(calls) {
+    const nodes = [];
+    const nodesByKey = new Map();
+    const edges = [];
+    let previousNodeId = "start";
+    for (const [index, call] of calls.entries()) {
+        const descriptor = targetNode(call);
+        let node = nodesByKey.get(descriptor.key);
+        if (!node) {
+            node = { id: `node-${nodes.length + 1}`, ...descriptor, callIds: [] };
+            nodesByKey.set(descriptor.key, node);
+            nodes.push(node);
+        }
+        node.callIds.push(call.id);
+        edges.push({
+            id: `edge-${index + 1}`,
+            from: previousNodeId,
+            to: node.id,
+            order: index + 1,
+            callId: call.id,
+            durationMs: round(call.durationMs),
+            outcome: call.outcome
+        });
+        previousNodeId = node.id;
+    }
+    return { basis: "raw_mcp", nodes, edges };
+}
+export function buildSessionModel(sessionId, events, webBaseUrl, now = Date.now()) {
+    const started = new Map();
+    const completed = new Set();
+    const annotations = [];
+    const calls = [];
+    const base = webBaseUrl.replace(/\/$/, "");
+    for (const event of events) {
+        if (event.type === "mcp_request_started")
+            started.set(event.callId, event);
+        if (event.type === "ai_annotation") {
+            annotations.push({
+                callId: event.callId,
+                severity: event.severity ?? "info",
+                title: event.title,
+                summary: event.summary,
+                cause: event.cause,
+                suggestion: event.suggestion,
+                author: event.author ?? "agent",
+                timestamp: event.timestamp
+            });
+        }
+        if (event.type === "mcp_request_completed" || event.type === "mcp_request_failed") {
+            const payload = event;
+            const callId = payload.callId ?? "";
+            const begin = started.get(callId);
+            completed.add(callId);
+            const beginBody = (begin?.body ?? null);
+            const label = requestLabel(beginBody);
+            const error = event.type === "mcp_request_failed"
+                ? (payload.error ?? "proxy or upstream connection failed")
+                : responseError(payload.body, payload.status ?? null);
+            calls.push({
+                id: callId,
+                sequence: begin?.sequence ?? event.sequence,
+                startedAt: begin?.timestamp ?? event.timestamp,
+                completedAt: event.timestamp,
+                durationMs: payload.durationMs ?? null,
+                statusCode: payload.status ?? null,
+                outcome: error ? "error" : "success",
+                error,
+                request: beginBody,
+                response: (payload.body ?? null),
+                requestHeaders: (begin?.headers ?? null),
+                responseHeaders: (payload.headers ?? null),
+                timing: timing(payload),
+                clientSource: begin?.clientSource ?? "agent",
+                operationId: begin?.operationId,
+                operationTitle: begin?.operationTitle,
+                operationStep: begin?.operationStep,
+                deepLink: `${base}/sessions/${sessionId}?call=${callId}`,
+                annotations: [],
+                isSystem: false,
+                ...label
+            });
+        }
+    }
+    for (const [callId, begin] of started) {
+        if (completed.has(callId))
+            continue;
+        const label = requestLabel((begin.body ?? null));
+        calls.push({
+            id: callId,
+            sequence: begin.sequence,
+            startedAt: begin.timestamp,
+            completedAt: null,
+            durationMs: Math.max(0, now - new Date(begin.timestamp).getTime()),
+            statusCode: null,
+            outcome: "running",
+            error: null,
+            request: (begin.body ?? null),
+            response: null,
+            requestHeaders: (begin.headers ?? null),
+            responseHeaders: null,
+            timing: null,
+            clientSource: begin.clientSource ?? "agent",
+            operationId: begin.operationId,
+            operationTitle: begin.operationTitle,
+            operationStep: begin.operationStep,
+            deepLink: `${base}/sessions/${sessionId}?call=${callId}`,
+            annotations: [],
+            isSystem: false,
+            ...label
+        });
+    }
+    for (const call of calls) {
+        call.isSystem = call.clientSource === "smoke-test" || call.category === "connection" || call.category === "discovery";
+    }
+    const workCalls = calls.filter((call) => !call.isSystem);
+    const errors = workCalls.filter((call) => call.outcome === "error").length;
+    const running = workCalls.filter((call) => call.outcome === "running").length;
+    const completedWork = workCalls.filter((call) => call.outcome !== "running");
+    const recent = [...completedWork].sort((a, b) => b.sequence - a.sequence).slice(0, 20);
+    // Per-tool baseline so the viewer can flag calls that are unusually slow for this session
+    const durationsByTool = new Map();
+    for (const call of completedWork) {
+        const values = durationsByTool.get(call.title) ?? [];
+        values.push(call.durationMs ?? 0);
+        durationsByTool.set(call.title, values);
+    }
+    for (const call of completedWork) {
+        const samples = durationsByTool.get(call.title) ?? [];
+        const baseline = median(samples);
+        const ratio = baseline ? (call.durationMs ?? 0) / baseline : 1;
+        call.performance = {
+            sampleCount: samples.length,
+            medianMs: round(baseline),
+            ratio: round(ratio),
+            classification: samples.length >= 3 && ratio >= 2 && (call.durationMs ?? 0) >= 50 ? "slow" : "normal"
+        };
+    }
+    for (const call of calls) {
+        const latestByAuthor = new Map();
+        for (const note of annotations.filter((item) => item.callId === call.id)) {
+            latestByAuthor.set(note.author, note);
+        }
+        call.annotations = [...latestByAuthor.values()];
+    }
+    const chronological = [...workCalls].sort((a, b) => a.sequence - b.sequence);
+    return {
+        id: sessionId,
+        startedAt: events.find((event) => event.type === "session_started")?.timestamp,
+        lastEventAt: events.at(-1)?.timestamp,
+        summary: {
+            totalCalls: workCalls.length,
+            successes: completedWork.length - errors,
+            errors,
+            running,
+            systemCalls: calls.length - workCalls.length,
+            averageDurationMs: recent.length
+                ? Math.round(recent.reduce((sum, call) => sum + (call.durationMs ?? 0), 0) / recent.length)
+                : 0,
+            medianDurationMs: round(median(recent.map((call) => call.durationMs ?? 0)))
+        },
+        graph: buildFlowGraph(chronological),
+        calls: calls.sort((a, b) => b.sequence - a.sequence),
+        annotations,
+        rawEventCount: events.length
+    };
+}
+/** Normalize an error message for similarity matching: mask paths, UUIDs, hex, and numbers. */
+export function normalizeError(text) {
+    if (!text)
+        return null;
+    return text.toLowerCase()
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "<uuid>")
+        .replace(/[a-z]:\\[^\s"'`]+/g, "<path>")
+        .replace(/(?:\/[\w.-]+){2,}/g, "<path>")
+        .replace(/0x[0-9a-f]+/g, "<hex>")
+        .replace(/\d+/g, "<n>")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 500);
+}
+//# sourceMappingURL=session-model.js.map

package/dist/session-model.js.map

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

package/dist/session-store.d.ts

@@ -0,0 +1,50 @@
+import type { ActiveSession, JsonObject, SessionEvent } from "./types.js";
+export type EventListener = (event: SessionEvent) => void | Promise<void>;
+export interface SessionStoreOptions {
+    /** Envelope source tag. Defaults to "unreal-mcp-proxy". */
+    source?: string;
+    /** Optional metadata stamped on every event (user/machine/project). */
+    identity?: JsonObject | null;
+    now?: () => Date;
+}
+/**
+ * Append-only JSONL session store.
+ * An observation session survives proxy and Unreal Editor restarts; it only rolls over
+ * when the user explicitly clears it. Event sinks attach via subscribe() and are awaited,
+ * so a sink can persist events durably in the same write chain.
+ */
+export declare class SessionStore {
+    readonly dataDir: string;
+    readonly sessionsDir: string;
+    private readonly activePath;
+    private readonly webBaseUrl;
+    private readonly source;
+    private readonly identity;
+    private readonly now;
+    session: ActiveSession | null;
+    private writeChain;
+    private readonly listeners;
+    constructor(dataDir: string, webBaseUrl: string, options?: SessionStoreOptions);
+    initialize(): Promise<ActiveSession>;
+    createSession(reason?: string): Promise<ActiveSession & {
+        url: string;
+    }>;
+    describe(): ActiveSession & {
+        url: string;
+    };
+    clear(): Promise<{
+        previous: ActiveSession & {
+            url: string;
+        };
+        current: ActiveSession & {
+            url: string;
+        };
+    }>;
+    append(type: string, payload?: Record<string, unknown>): Promise<SessionEvent>;
+    withWriteLock<T>(action: () => Promise<T>): Promise<T>;
+    /** Attach an event sink. Listeners are awaited inside the write chain. Returns an unsubscribe fn. */
+    subscribe(listener: EventListener): () => void;
+    eventPath(sessionId: string): string;
+    readEvents(sessionId?: string): Promise<SessionEvent[]>;
+    private persistActive;
+}

package/dist/session-store.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile, appendFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Append-only JSONL session store.
+ * An observation session survives proxy and Unreal Editor restarts; it only rolls over
+ * when the user explicitly clears it. Event sinks attach via subscribe() and are awaited,
+ * so a sink can persist events durably in the same write chain.
+ */
+export class SessionStore {
+    dataDir;
+    sessionsDir;
+    activePath;
+    webBaseUrl;
+    source;
+    identity;
+    now;
+    session = null;
+    writeChain = Promise.resolve();
+    listeners = new Set();
+    constructor(dataDir, webBaseUrl, options = {}) {
+        this.dataDir = dataDir;
+        this.webBaseUrl = webBaseUrl.replace(/\/$/, "");
+        this.source = options.source ?? "unreal-mcp-proxy";
+        this.identity = options.identity ?? null;
+        this.now = options.now ?? (() => new Date());
+        this.activePath = path.join(dataDir, "active-session.json");
+        this.sessionsDir = path.join(dataDir, "sessions");
+    }
+    async initialize() {
+        await mkdir(this.sessionsDir, { recursive: true });
+        try {
+            this.session = JSON.parse(await readFile(this.activePath, "utf8"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await this.createSession("initial_start");
+        }
+        return this.session;
+    }
+    async createSession(reason = "user_clear") {
+        this.session = { id: randomUUID(), createdAt: this.now().toISOString(), reason, sequence: 0 };
+        await this.persistActive();
+        await this.append("session_started", { reason });
+        return this.describe();
+    }
+    describe() {
+        return { ...this.session, url: `${this.webBaseUrl}/sessions/${this.session.id}` };
+    }
+    async clear() {
+        const previous = this.describe();
+        await this.append("session_closed", { reason: "user_clear" });
+        const current = await this.createSession("user_clear");
+        return { previous, current };
+    }
+    async append(type, payload = {}) {
+        return this.withWriteLock(async () => {
+            const session = this.session;
+            const event = {
+                ...payload,
+                schemaVersion: 2,
+                source: this.source,
+                sessionId: session.id,
+                sequence: ++session.sequence,
+                timestamp: this.now().toISOString(),
+                type,
+                identity: this.identity
+            };
+            await appendFile(this.eventPath(session.id), `${JSON.stringify(event)}\n`, "utf8");
+            await this.persistActive();
+            for (const listener of this.listeners) {
+                try {
+                    await listener(event);
+                }
+                catch { /* a sink must never break recording */ }
+            }
+            return event;
+        });
+    }
+    withWriteLock(action) {
+        const result = this.writeChain.then(action);
+        this.writeChain = result.catch(() => { });
+        return result;
+    }
+    /** Attach an event sink. Listeners are awaited inside the write chain. Returns an unsubscribe fn. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    eventPath(sessionId) {
+        return path.join(this.sessionsDir, `${sessionId}.jsonl`);
+    }
+    async readEvents(sessionId = this.session.id) {
+        try {
+            const text = await readFile(this.eventPath(sessionId), "utf8");
+            return text.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    async persistActive() {
+        const temporaryPath = `${this.activePath}.tmp`;
+        await writeFile(temporaryPath, JSON.stringify(this.session, null, 2), "utf8");
+        await rename(temporaryPath, this.activePath);
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/session-store.js.map

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

package/dist/sinks.d.ts

@@ -0,0 +1,49 @@
+import type { ProxyConfig } from "./config.js";
+import type { SessionStore } from "./session-store.js";
+import type { SessionEvent } from "./types.js";
+/**
+ * Event sinks: forward recorded events somewhere else (a team server, a message queue,
+ * a log shipper) without touching the proxy core. A sink is an ES module listed in the
+ * config, either as a plain path or with injected options:
+ *
+ *   "sinks": [
+ *     "./my-sink.mjs",
+ *     { "module": "@myteam/collector-sink", "options": { "url": "https://...", "token": "..." } }
+ *   ]
+ *
+ * `module` may be a relative path (resolved against the config file's directory), an
+ * absolute path, or a bare npm specifier. The default export is a factory:
+ *
+ *   export default function createSink({ config, options, log }) {
+ *     return {
+ *       onEvent(event) { ... },          // awaited; errors are swallowed per-event
+ *       async close() { ... }            // optional; called on shutdown
+ *     };
+ *   }
+ *
+ * Recording locally always comes first: a sink that throws never breaks recording.
+ * A sink that fails to LOAD, however, fails startup - a misconfigured monitoring
+ * pipeline should be visible, not silent.
+ */
+export type SinkSpec = string | {
+    module: string;
+    options?: unknown;
+};
+export interface SinkContext {
+    config: ProxyConfig;
+    /** The `options` value from this sink's config entry (undefined for plain-path entries). */
+    options: unknown;
+    log: (message: string) => void;
+}
+export interface Sink {
+    onEvent: (event: SessionEvent) => void | Promise<void>;
+    close?: () => void | Promise<void>;
+}
+export type SinkFactory = (context: SinkContext) => Sink | Promise<Sink>;
+export interface AttachedSink {
+    modulePath: string;
+    sink: Sink;
+    unsubscribe: () => void;
+}
+export declare function loadSinks(store: SessionStore, config: ProxyConfig, log: (message: string) => void): Promise<AttachedSink[]>;
+export declare function closeSinks(sinks: AttachedSink[]): Promise<void>;

package/dist/sinks.js

@@ -0,0 +1,42 @@
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+function resolveSpecifier(module, baseDir) {
+    if (module.startsWith("./") || module.startsWith("../")) {
+        return pathToFileURL(path.resolve(baseDir, module)).href;
+    }
+    if (path.isAbsolute(module))
+        return pathToFileURL(module).href;
+    return module; // bare specifier: an npm package (e.g. a team-published sink)
+}
+export async function loadSinks(store, config, log) {
+    const attached = [];
+    for (const spec of config.sinks) {
+        const { module, options } = typeof spec === "string" ? { module: spec, options: undefined } : spec;
+        const specifier = resolveSpecifier(module, config.baseDir);
+        let factory;
+        try {
+            const loaded = await import(specifier);
+            if (typeof loaded.default !== "function")
+                throw new Error("default export is not a sink factory function");
+            factory = loaded.default;
+        }
+        catch (error) {
+            throw new Error(`failed to load sink "${module}": ${error.message}`);
+        }
+        const sink = await factory({ config, options, log });
+        const unsubscribe = store.subscribe((event) => sink.onEvent(event));
+        attached.push({ modulePath: module, sink, unsubscribe });
+        log(`sink attached: ${module}`);
+    }
+    return attached;
+}
+export async function closeSinks(sinks) {
+    for (const { sink, unsubscribe } of sinks) {
+        unsubscribe();
+        try {
+            await sink.close?.();
+        }
+        catch { /* shutdown must not fail on a sink */ }
+    }
+}
+//# sourceMappingURL=sinks.js.map

package/dist/sinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.js","sourceRoot":"","sources":["../src/sinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAoD7B,SAAS,gBAAgB,CAAC,MAAc,EAAE,OAAe;IACvD,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;IAC/D,OAAO,MAAM,CAAC,CAAC,8DAA8D;AAC/E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAmB,EAAE,MAAmB,EAAE,GAA8B;IACtG,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACnG,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,OAAoB,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAA8B,CAAC;YACpE,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU;gBAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAC3G,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,MAAO,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,GAAG,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAqB;IACpD,KAAK,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,KAAK,EAAE,CAAC;QAC1C,WAAW,EAAE,CAAC;QACd,IAAI,CAAC;YAAC,MAAM,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,sCAAsC,CAAC,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/stdio-bridge.d.ts

@@ -0,0 +1,3 @@
+import type { ProxyConfig } from "./config.js";
+export declare function ensureDaemon(config: ProxyConfig): Promise<string>;
+export declare function runStdioBridge(config: ProxyConfig): Promise<void>;