devframe 0.8.2 → 0.9.0-beta.1

package/dist/instance-shell-KRdee1QF.mjs

@@ -0,0 +1,485 @@
+import "./constants.mjs";
+import { t as diagnostics } from "./diagnostics-DLYH5oD3.mjs";
+import { t as getInternalContext } from "./context-C33rR7n0.mjs";
+import { createInteractiveAuth } from "./recipes/interactive-auth.mjs";
+import { createServer } from "node:http";
+import process from "node:process";
+import { isIP } from "node:net";
+import { joinURL, withLeadingSlash, withoutLeadingSlash, withoutTrailingSlash } from "ufo";
+import { H3, defineHandler, toNodeHandler } from "h3";
+//#region src/node/utils.ts
+const NON_DIALABLE_HOSTS = /* @__PURE__ */ new Set([
+	"0.0.0.0",
+	"127.0.0.1",
+	"::",
+	"0000:0000:0000:0000:0000:0000:0000:0000",
+	""
+]);
+/** Map a bind host to a host a client can actually connect to. */
+function toDialableHost(host) {
+	return NON_DIALABLE_HOSTS.has(host) ? "localhost" : host;
+}
+/** Format a bind host for use in a URL authority (dialable, IPv6-bracketed). */
+function formatHostForUrl(host) {
+	const dialable = toDialableHost(host);
+	return isIP(dialable) === 6 ? `[${dialable}]` : dialable;
+}
+function normalizeHttpServerUrl(host, port) {
+	return `http://${formatHostForUrl(host)}:${port}`;
+}
+//#endregion
+//#region src/node/instance-shell.ts
+/**
+* Compose an h3 + WebSocket RPC server for a devframe context — the low-level
+* "listen on a port (or share one) + attach the WS transport" binding the
+* side-car and shared-server tiers below are built on. Owns and listens on a
+* fresh `node:http` server unless `server` is supplied, in which case it only
+* attaches the upgrade listener and leaves that server's lifecycle to its
+* owner.
+*/
+async function bindHttpAndWs(options) {
+	const { context, port, core } = options;
+	const bindHost = options.host;
+	const app = new H3();
+	const ownsHttpServer = !options.server;
+	const httpServer = options.server ?? createServer(toNodeHandler(app));
+	const rpcHost = context.rpc;
+	const websocket = options.websocket !== false;
+	let ws;
+	let closeWs = async () => {};
+	if (websocket) {
+		const { attachWsRpcTransport } = await import("./rpc/transports/ws-server.mjs");
+		const transport = attachWsRpcTransport(core.rpcGroup, {
+			server: httpServer,
+			path: options.path,
+			destroyUnmatched: options.destroyUnmatched ?? ownsHttpServer,
+			allowedOrigins: options.allowedOrigins,
+			onConnected: core.onConnected,
+			onDisconnected: core.onDisconnected
+		});
+		ws = transport.ws;
+		closeWs = transport.close;
+	}
+	if (ownsHttpServer) try {
+		await new Promise((resolve, reject) => {
+			const onError = (error) => reject(error);
+			httpServer.once("error", onError);
+			httpServer.listen(port, bindHost, () => {
+				httpServer.removeListener("error", onError);
+				resolve();
+			});
+		});
+	} catch (error) {
+		await closeWs().catch(() => {});
+		throw diagnostics.DF0052({
+			host: bindHost,
+			port,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+	const address = httpServer.address();
+	const resolvedPort = typeof address === "object" && address ? address.port : port;
+	const origin = normalizeHttpServerUrl(bindHost, resolvedPort);
+	const internal = getInternalContext(context);
+	const wsUrl = `ws://${formatHostForUrl(bindHost)}:${resolvedPort}${options.path ?? ""}`;
+	if (websocket) internal.wsEndpoint = { url: wsUrl };
+	function connectionMeta() {
+		const jsonSerializableMethods = [];
+		for (const def of rpcHost.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);
+		return {
+			backend: "websocket",
+			websocket: { path: options.path },
+			jsonSerializableMethods
+		};
+	}
+	return {
+		origin,
+		port: resolvedPort,
+		app,
+		ws,
+		rpcGroup: core.rpcGroup,
+		connectionMeta,
+		async close() {
+			await closeWs();
+			if (ownsHttpServer) await new Promise((r) => httpServer.close(() => r()));
+			if (websocket && getInternalContext(context).wsEndpoint?.url === wsUrl) getInternalContext(context).wsEndpoint = void 0;
+		}
+	};
+}
+/**
+* Translate the public `register?: boolean | Partial<DevframeInstanceRecord>`
+* option into a shell {@link InstanceRegisterConfig}, or `undefined` when
+* registration is opted out. The object form supplies record overrides on top
+* of the caller-provided identity defaults.
+*/
+function resolveInstanceRegister(option, defaults) {
+	if (!option) return void 0;
+	return {
+		id: defaults.id,
+		...defaults.name !== void 0 ? { name: defaults.name } : {},
+		...defaults.rootDir !== void 0 ? { rootDir: defaults.rootDir } : {},
+		...typeof option === "object" ? { overrides: option } : {}
+	};
+}
+/** Compare two URL paths ignoring a trailing slash. */
+function samePath(a, b) {
+	return withoutTrailingSlash(a) === withoutTrailingSlash(b);
+}
+/**
+* Copy a web `Response` from a fetch-style transport handler onto the h3
+* event's response and return its body — mirroring the MCP route's bridge.
+* Returning the body (a `ReadableStream`, or `''` for an empty one — h3
+* middleware only falls through on `undefined`) terminates the chain with
+* the status/headers set here instead of continuing to the SPA catch-all.
+*/
+function respondWith(event, response) {
+	event.res.status = response.status;
+	event.res.statusText = response.statusText;
+	response.headers.forEach((value, key) => {
+		event.res.headers.set(key, value);
+	});
+	return response.body ?? "";
+}
+/**
+* The shared machinery behind `initDevframe` and `initHub`: one mount base,
+* one h3 app, one lazily-derived public origin (and the auth banner that waits
+* for it), one WebSocket binding, and the fetch / connect-middleware pair that
+* serves them. Each factory supplies only what makes it itself — its context,
+* its routes, its diagnostics — through `init` / `mount`.
+*
+* Nothing here listens on a port unless a side-car was explicitly requested:
+* the default tier leaves the socket `unbound`, so a host chains it onto its
+* own server through {@link InstanceShell.attach} /
+* {@link InstanceShell.handleUpgrade}.
+*
+* @internal
+*/
+function createInstanceShell(options) {
+	const base = options.base;
+	const baseNoSlash = withoutTrailingSlash(base);
+	const app = options.app ?? new H3();
+	const wsDisabled = options.ws === false;
+	const ws = options.ws === false ? {} : options.ws ?? {};
+	const route = withoutLeadingSlash(ws.route ?? "__ws");
+	/** Where an upgrade lands on the host's own origin. */
+	const routePath = joinURL(base, route);
+	/** What `__connection.json` advertises for a same-origin socket. */
+	const advertisedPath = options.absoluteWsPath ? routePath : route;
+	const sidecarRequested = ws.port != null || ws.sidecar === true;
+	const tier = wsDisabled ? "disabled" : sidecarRequested ? "sidecar" : options.server ? "server" : ws.url ? "external" : "unbound";
+	const sseEnabled = options.sse !== false && tier !== "external";
+	const sseRoute = withoutLeadingSlash((typeof options.sse === "object" ? options.sse.route : void 0) ?? "__sse");
+	const sseRoutePath = joinURL(base, sseRoute);
+	const advertisedSsePath = options.absoluteWsPath ? sseRoutePath : sseRoute;
+	let derivedOrigin;
+	function currentOrigin() {
+		return (typeof options.origin === "function" ? options.origin() : options.origin) || derivedOrigin;
+	}
+	let authHandler;
+	let bannerPrinted = false;
+	function maybePrintBanner() {
+		if (bannerPrinted || !authHandler || !currentOrigin()) return;
+		bannerPrinted = true;
+		authHandler.printBanner();
+	}
+	let meta;
+	let registration;
+	let registerPromise;
+	/**
+	* Publish the instance in the global registry the moment both its origin
+	* and connection meta are known — at init end for a pinned origin, or on
+	* the first request for a derived one. Registration never throws (the
+	* registry writer degrades to a coded warning), so failures never surface.
+	*/
+	function maybeRegister() {
+		const cfg = options.register;
+		const origin = currentOrigin();
+		if (!cfg || registerPromise || !origin || !meta) return;
+		const resolvedMeta = meta;
+		registerPromise = import("./instance-registry-BQqGoDO9.mjs").then((n) => n.t).then(({ registerDevframeInstance }) => {
+			let port = 0;
+			try {
+				const url = new URL(origin);
+				port = Number(url.port) || (url.protocol === "https:" ? 443 : 80);
+			} catch {}
+			registration = registerDevframeInstance({
+				pid: process.pid,
+				port,
+				origin,
+				basePath: base,
+				id: cfg.id,
+				...cfg.name !== void 0 ? { name: cfg.name } : {},
+				rootDir: cfg.rootDir ?? process.cwd(),
+				mcp: resolvedMeta.mcp ? { path: joinURL(base, resolvedMeta.mcp.path) } : null,
+				startedAt: Date.now(),
+				...cfg.overrides
+			});
+		}).catch(() => {});
+	}
+	function noteOrigin(origin) {
+		derivedOrigin ??= origin;
+		maybePrintBanner();
+		maybeRegister();
+	}
+	let started;
+	let transport;
+	let dispose;
+	let ctx;
+	const api = {
+		base,
+		app,
+		origin: currentOrigin,
+		connectionMeta: () => meta
+	};
+	/**
+	* Auth resolution: gate by default, `false` opts out, a handler object
+	* installs a custom scheme. The `external` tier has no local transport to
+	* gate — the server behind `ws.url` owns auth — so it resolves to nothing.
+	*/
+	function resolveAuth() {
+		if (options.auth === false) return false;
+		if (typeof options.auth === "object") {
+			authHandler = options.auth;
+			return options.auth;
+		}
+		authHandler = createInteractiveAuth(ctx);
+		return authHandler;
+	}
+	/**
+	* The context's RPC core (birpc group, session lifecycle, auth gate) —
+	* one per instance, shared by every transport binding (WS and SSE), so a
+	* WS peer and an SSE session live in the same session/broadcast space.
+	* Built lazily: an `unbound` host that never wires a transport pays
+	* nothing for it, not even the imports. `resolvedAuth` and `ctx` are
+	* assigned during `init()` before any caller can reach this.
+	*/
+	let resolvedAuth = false;
+	let corePromise;
+	function ensureCore() {
+		corePromise ??= import("./rpc-core-CqcJkAu9.mjs").then((n) => n.n).then(({ createContextRpcServer }) => createContextRpcServer({
+			context: ctx,
+			auth: resolvedAuth,
+			onPeerConnect: options.onPeerConnect,
+			onPeerDisconnect: options.onPeerDisconnect
+		}));
+		return corePromise;
+	}
+	/**
+	* The SSE transport, built on the first request to its route so an
+	* instance nobody dials over SSE never loads it.
+	*/
+	let ssePromise;
+	function ensureSse() {
+		ssePromise ??= (async () => {
+			const [core, { attachSseRpcTransport }] = await Promise.all([ensureCore(), import("./rpc/transports/sse-server.mjs")]);
+			return attachSseRpcTransport(core.rpcGroup, {
+				allowedOrigins: options.allowedOrigins,
+				onConnected: core.onConnected,
+				onDisconnected: core.onDisconnected
+			});
+		})();
+		return ssePromise;
+	}
+	/**
+	* A side-car server on its own port. `getPort` probes and the bind can
+	* still race (or disagree across the v4/v6 duals of `localhost`), so an
+	* auto-port side-car retries on a fresh random port instead of failing
+	* init; a pinned `ws.port` is honored as given and fails loudly.
+	*/
+	async function startSidecar(core) {
+		const sidecarHost = options.host ?? "localhost";
+		const start = (port) => bindHttpAndWs({
+			context: ctx,
+			core,
+			host: sidecarHost,
+			port,
+			path: withLeadingSlash(route),
+			allowedOrigins: options.allowedOrigins
+		});
+		if (ws.port != null) return await start(ws.port);
+		const { getPort } = await import("./dist-D8jAMwxU.mjs").then((n) => n.t);
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const port = attempt === 0 && options.resolveSidecarPort ? await options.resolveSidecarPort(sidecarHost) : await getPort({
+				random: true,
+				host: sidecarHost
+			});
+			try {
+				return await start(port);
+			} catch (error) {
+				lastError = error;
+			}
+		}
+		throw lastError;
+	}
+	async function init() {
+		const result = await options.init(api);
+		ctx = result.context;
+		dispose = result.dispose;
+		resolvedAuth = tier === "external" ? false : resolveAuth();
+		let websocketMeta;
+		if (tier === "sidecar") {
+			started = await startSidecar(await ensureCore());
+			websocketMeta = {
+				port: started.port,
+				path: route
+			};
+		} else if (tier === "server") {
+			started = await bindHttpAndWs({
+				context: ctx,
+				core: await ensureCore(),
+				host: options.host ?? "localhost",
+				port: 0,
+				server: options.server,
+				path: routePath,
+				allowedOrigins: options.allowedOrigins,
+				destroyUnmatched: options.destroyUnmatchedUpgrades
+			});
+			websocketMeta = { path: advertisedPath };
+		} else if (tier === "external") websocketMeta = ws.url;
+		else if (tier === "unbound") websocketMeta = { path: advertisedPath };
+		if (!wsDisabled && ws.url) websocketMeta = ws.url;
+		if (sseEnabled) app.use(sseRoutePath, defineHandler(async (event) => respondWith(event, await (await ensureSse()).handler(event.req))));
+		meta = {
+			backend: wsDisabled ? sseEnabled ? "sse" : "none" : "websocket",
+			...websocketMeta !== void 0 ? { websocket: websocketMeta } : {},
+			...sseEnabled ? { sse: { path: advertisedSsePath } } : {},
+			...result.mcp ? { mcp: result.mcp } : {}
+		};
+		await options.mount?.(ctx, meta, api);
+		maybePrintBanner();
+		maybeRegister();
+	}
+	const initPromise = init();
+	initPromise.catch(() => {});
+	const contextPromise = initPromise.then(() => ctx);
+	contextPromise.catch(() => {});
+	/**
+	* The `unbound` tier: the RPC core and its crossws adapter, bound to
+	* nothing. Built on the first `attach` / `handleUpgrade` — a host that
+	* never wires the socket (or whose runtime brings its own WS transport)
+	* pays nothing for it, not even the adapter's imports.
+	*/
+	let transportPromise;
+	function ensureTransport() {
+		transportPromise ??= initPromise.then(async () => {
+			const [core, { attachWsRpcTransport }] = await Promise.all([ensureCore(), import("./rpc/transports/ws-server.mjs")]);
+			transport = attachWsRpcTransport(core.rpcGroup, {
+				unbound: true,
+				path: routePath,
+				allowedOrigins: options.allowedOrigins,
+				onConnected: core.onConnected,
+				onDisconnected: core.onDisconnected
+			});
+			return transport;
+		});
+		return transportPromise;
+	}
+	async function handleRequest(request) {
+		await initPromise;
+		noteOrigin(new URL(request.url).origin);
+		const response = await app.fetch(request);
+		if (response.status === 404) return new Response(null, { status: 404 });
+		return response;
+	}
+	let nodeHandler;
+	function nodeMiddleware(req, res, next) {
+		let pathname = req.url ?? "/";
+		try {
+			pathname = new URL(pathname, "http://localhost").pathname;
+		} catch {}
+		if (!(samePath(pathname, baseNoSlash) || pathname.startsWith(base))) {
+			if (next) {
+				next();
+				return;
+			}
+			res.statusCode = 404;
+			res.end();
+			return;
+		}
+		initPromise.then(async () => {
+			const host = req.headers.host;
+			if (host) {
+				const encrypted = req.socket.encrypted;
+				noteOrigin(`${encrypted ? "https" : "http"}://${host}`);
+			}
+			if (!nodeHandler) {
+				const { toNodeHandler } = await import("h3/node");
+				nodeHandler = toNodeHandler(app);
+			}
+			return nodeHandler(req, res);
+		}).catch((err) => {
+			if (next) {
+				next(err);
+				return;
+			}
+			res.statusCode = 500;
+			res.end();
+		});
+	}
+	/** The `unbound` tier is the only one whose socket the host may drive. */
+	function assertUnbound() {
+		if (tier === "disabled") throw diagnostics.DF0057();
+		if (tier === "external") throw diagnostics.DF0056({ url: ws.url });
+		if (tier !== "unbound") throw diagnostics.DF0055({ tier });
+	}
+	/**
+	* Publish the socket's absolute URL on the context, so surfaces that hand
+	* out a complete endpoint (the hub's remote docks) work on this tier too.
+	* {@link bindHttpAndWs} does the same for the tiers it owns.
+	*/
+	function publishWsEndpoint(server) {
+		const record = () => {
+			const address = server.address();
+			if (typeof address !== "object" || !address) return;
+			const host = options.host ?? (address.address === "::" || address.address === "0.0.0.0" ? "localhost" : address.address);
+			getInternalContext(ctx).wsEndpoint = { url: `ws://${formatHostForUrl(host)}:${address.port}${routePath}` };
+		};
+		if (server.listening) record();
+		else server.once("listening", record);
+	}
+	function handleUpgrade(req, socket, head) {
+		assertUnbound();
+		if (transport) {
+			transport.handleUpgrade(req, socket, head);
+			return;
+		}
+		ensureTransport().then((live) => live.handleUpgrade(req, socket, head)).catch(() => socket.destroy());
+	}
+	function attach(server) {
+		assertUnbound();
+		server.on("upgrade", handleUpgrade);
+		ensureTransport().then(() => publishWsEndpoint(server)).catch(() => {});
+		return () => server.off("upgrade", handleUpgrade);
+	}
+	return {
+		base,
+		handler: handleRequest,
+		nodeMiddleware,
+		ready: initPromise,
+		context: contextPromise,
+		connectionMeta: () => meta ?? options.onMetaUnavailable(),
+		handleUpgrade,
+		attach,
+		async close() {
+			await initPromise.catch(() => {});
+			await registerPromise?.catch(() => {});
+			registration?.unregister();
+			await dispose?.();
+			await ssePromise?.then((live) => live.close()).catch(() => {});
+			await started?.close();
+			await transportPromise?.then((live) => live.close()).catch(() => {});
+		},
+		internals: {
+			get started() {
+				return started;
+			},
+			get authHandler() {
+				return authHandler;
+			}
+		}
+	};
+}
+//#endregion
+export { normalizeHttpServerUrl as i, resolveInstanceRegister as n, samePath as r, createInstanceShell as t };

package/dist/internal/index.d.mts

@@ -0,0 +1,150 @@
+import { At as DevframeAgentHost$1, Ct as AgentResource, Dt as AgentToolInput, Et as AgentTool, Mt as EventEmitter, Ot as AgentToolProvider, St as AgentManifest, Tt as AgentResourceInput, jt as DevframeAgentHostEvents, kt as AgentToolProviderHandle, wt as AgentResourceContent, x as DevframeNodeContext, xt as AgentHandle, z as DevframeHost } from "../devframe-Bdd9YXTy.mjs";
+import { v as RpcFunctionDefinitionAny } from "../types-CnJSgRVa.mjs";
+import { a as InstanceShellInit, c as StartedServer, d as samePath, f as DevframeInstanceRecord, h as registerDevframeInstance, i as InstanceShellApi, l as createInstanceShell, m as listLiveDevframeInstances, n as InstanceRegisterConfig, o as InstanceShellInternals, p as DevframeInstanceRegistration, r as InstanceShell, s as InstanceWsTier, t as CreateInstanceShellOptions, u as resolveInstanceRegister } from "../instance-shell-DBTXTSjN.mjs";
+import { n as CreateContextRpcServerOptions, r as createContextRpcServer, t as ContextRpcServer } from "../rpc-core-CGctXToO.mjs";
+//#region src/node/agent-args.d.ts
+/**
+ * How {@link coerceAgentPositionalArgs} treats an args object that carries
+ * neither declared schemas nor `arg0`/`arg1`/… keys:
+ *
+ * - `'wrap'` — pass the object itself as the single positional argument.
+ *   RPC-backed tools use this: an untyped RPC may take one raw object.
+ * - `'drop'` — call with zero arguments. Command-backed tools use this:
+ *   a handler's positional parameters come solely from its declared
+ *   `agent.args` schemas, so undeclared payload is ignored.
+ */
+type AgentArgsFallback = 'wrap' | 'drop';
+/**
+ * Map the args payload an agent surface receives (MCP sends an object
+ * keyed `arg0`/`arg1`/…, matching the schema the adapter advertises) onto
+ * a handler's positional parameters. Shared by the agent host's RPC
+ * bridge and the hub's command-derived tools so the coercion cannot
+ * drift between them.
+ *
+ * - an array passes through as-is
+ * - `null`/`undefined` become a zero-argument call
+ * - with declared schemas, each schema reads its own `argN` key, in order
+ * - without schemas, `arg0`/`arg1`/… keys are collected when present
+ * - an empty object becomes a zero-argument call
+ * - anything else follows the {@link AgentArgsFallback}
+ *
+ * @experimental
+ */
+declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unknown[] | undefined, fallback?: AgentArgsFallback): unknown[];
+//#endregion
+//#region src/node/host-agent.d.ts
+/**
+ * Framework-neutral host aggregating the agent-exposed surface of a
+ * devframe. Auto-discovers RPC functions with an `agent` field from
+ * `ctx.rpc.definitions`, and accepts plugin-registered tools /
+ * resources via `registerTool` / `registerResource`.
+ *
+ * @experimental
+ */
+declare class DevframeAgentHost implements DevframeAgentHost$1 {
+  readonly context: DevframeNodeContext;
+  readonly events: EventEmitter<DevframeAgentHostEvents>;
+  private readonly tools;
+  private readonly resources;
+  private readonly providers;
+  private _rpcUnsubscribe;
+  constructor(context: DevframeNodeContext);
+  registerTool(input: AgentToolInput): AgentHandle;
+  unregisterTool(id: string): boolean;
+  registerToolProvider(provider: AgentToolProvider): AgentToolProviderHandle;
+  registerResource(input: AgentResourceInput): AgentHandle;
+  unregisterResource(id: string): boolean;
+  list(): AgentManifest;
+  getTool(id: string): AgentTool | undefined;
+  getResource(id: string): AgentResource | undefined;
+  invoke(id: string, args: unknown): Promise<unknown>;
+  read(id: string): Promise<AgentResourceContent>;
+  /** @internal */
+  _dispose(): void;
+  private _validateToolId;
+  private _projectTool;
+  /** Query every registered provider, projecting inputs to serializable tools. */
+  private _collectProviderTools;
+  private _collectRpcTools;
+  private _findRpcDefinition;
+}
+//#endregion
+//#region src/node/host-h3.d.ts
+interface CreateH3DevframeHostOptions {
+  /** The h3 app instance — registered once the CLI adapter lands. */
+  app?: unknown;
+  /**
+   * Host the standalone server listens on, e.g. `http://localhost:9999`.
+   * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
+   * Pass a function for hosts that only learn their public origin later
+   * (e.g. `createHandler` derives it from the first incoming request).
+   */
+  origin: string | (() => string);
+  /**
+   * Register a static-file handler at `base` serving files from `distDir`.
+   * Wired into the h3 app once the CLI adapter lands (commit 5). For now
+   * the CLI isn't running, so the default is a no-op.
+   */
+  mount?: (base: string, distDir: string) => void | Promise<void>;
+  /**
+   * Namespace for storage paths returned by `getStorageDir`. Workspace
+   * state (committable) lives under `${workspaceRoot}/.devframe/`, project
+   * state under `${workspaceRoot}/node_modules/.<appName>/devframe/`, and
+   * global state under `${homedir()}/.<appName>/devframe/`. Pick the
+   * devtool's id (or another stable, filesystem-safe identifier) so the
+   * standalone host doesn't collide with other tools' storage.
+   */
+  appName: string;
+  /**
+   * Workspace root used as the parent of the per-project storage
+   * directory. Defaults to `process.cwd()`.
+   */
+  workspaceRoot?: string;
+}
+/**
+ * h3-backed {@link DevframeHost} — used by the standalone CLI adapter.
+ */
+declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): DevframeHost;
+//#endregion
+//#region src/node/utils.d.ts
+declare function normalizeHttpServerUrl(host: string, port: number | string): string;
+//#endregion
+//#region src/rpc/wire-codec.d.ts
+/**
+ * The per-connection `serialize`/`deserialize` pair for a live RPC wire.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+interface RpcWireCodec {
+  serialize: (msg: any) => string;
+  deserialize: (raw: string) => any;
+}
+/**
+ * Build the per-connection wire codec every live transport (WS server, WS
+ * client, SSE server, SSE client) shares: per-method dispatch between strict
+ * JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
+ * structured-clone (everything else, including all error envelopes), with a
+ * request-id → method map so a response independently picks the same
+ * encoder as its request. One codec per connection — request-id spaces
+ * don't collide across connections.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+declare function createRpcWireCodec(definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
+/**
+ * Peek at a wire frame's birpc envelope without engaging a codec's
+ * request-id bookkeeping — used by the SSE transport to route a frame
+ * (park a POST for its response / answer with a bare 202) before it is
+ * handed to birpc proper.
+ *
+ * @internal
+ * implementations; not part of the stable public API.
+ */
+declare function peekRpcWireFrame(raw: string): {
+  t?: string;
+  i?: string;
+};
+//#endregion
+export { type AgentArgsFallback, type ContextRpcServer, type CreateContextRpcServerOptions, CreateH3DevframeHostOptions, type CreateInstanceShellOptions, DevframeAgentHost, type DevframeInstanceRecord, type DevframeInstanceRegistration, type InstanceRegisterConfig, type InstanceShell, type InstanceShellApi, type InstanceShellInit, type InstanceShellInternals, type InstanceWsTier, type RpcWireCodec, type StartedServer, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, listLiveDevframeInstances, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveInstanceRegister, samePath };

package/dist/internal/index.mjs

@@ -0,0 +1,7 @@
+import { n as peekRpcWireFrame, t as createRpcWireCodec } from "../wire-codec-9VhIKnyp.mjs";
+import { n as coerceAgentPositionalArgs, t as DevframeAgentHost } from "../host-agent-CpbAoqBx.mjs";
+import { t as createH3DevframeHost } from "../host-h3-CzCZwtuV.mjs";
+import { i as registerDevframeInstance, n as listLiveDevframeInstances } from "../instance-registry-BQqGoDO9.mjs";
+import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, r as samePath, t as createInstanceShell } from "../instance-shell-KRdee1QF.mjs";
+import { t as createContextRpcServer } from "../rpc-core-CqcJkAu9.mjs";
+export { DevframeAgentHost, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, listLiveDevframeInstances, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveInstanceRegister, samePath };

package/dist/node/auth.d.mts

@@ -1,3 +1,3 @@
-import { p as DevframeAuthHandler } from "../devframe-mQ4qZAuo.mjs";
-import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-b64Uuhy2.mjs";
+import { p as DevframeAuthHandler } from "../devframe-Bdd9YXTy.mjs";
+import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-CZRd2K1C.mjs";
 export { DevframeAuthHandler, buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, refreshTempAuthCode, revokeActiveConnectionsForToken, revokeAuthToken, verifyAuthToken };

package/dist/node/hub-internals.d.mts

@@ -1,15 +1,3 @@
-import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
-import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-DoSozfvx.mjs";
-//#region src/adapters/_shared.d.ts
-/**
- * Resolve the mount base path for a devframe's SPA. Hosted adapters
- * (`vite`, `embedded`) default to `/__<id>/` so they don't collide
- * with the host app; standalone adapters (`cli`, `spa`, `build`)
- * default to `/` because they own the origin.
- *
- * The devframe author can override with `basePath` on the definition.
- */
-declare function resolveBasePath(def: DevframeDefinition, kind: DevframeDeploymentKind): string;
-declare function normalizeBasePath(base: string): string;
-//#endregion
+import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-CSCwoABx.mjs";
+import { n as normalizeBasePath, r as resolveBasePath } from "../_shared-DmpWW-HH.mjs";
 export { type DevframeInternalContext, type InternalAnonymousAuthStorage, type RemoteTokenRecord, getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };

package/dist/node/hub-internals.mjs

@@ -1,3 +1,3 @@
-import { n as internalContextMap, t as getInternalContext } from "../context-CBg8iRbQ.mjs";
-import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-bWRzeSa0.mjs";
+import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-CttmCMBi.mjs";
+import { n as internalContextMap, t as getInternalContext } from "../context-C33rR7n0.mjs";
 export { getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };