devframe 0.7.16 → 0.8.0

package/dist/{index-DgsLFhZg.d.mts → index-Dbw1p5ch.d.mts}

@@ -1,5 +1,5 @@
-import { C as RpcFunctionType, S as RpcFunctionSetupResult, T as RpcReturnSchema, _ as RpcFunctionDefinition, i as RpcArgsSchema, v as RpcFunctionDefinitionAny, w as RpcFunctionsCollector } from "./types-CrzNxXKq.mjs";
-import { a as getDefinitionsWithDumps$1, c as StaticRpcDumpManifest$1, d as StaticRpcDumpManifestValue$1, f as StaticRpcDumpSerialization$1, i as dumpFunctions$1, l as StaticRpcDumpManifestQueryEntry$1, n as serializeDumpError$1, o as StaticRpcDumpCollection$1, p as collectStaticRpcDump$1, r as createClientFromDump$1, s as StaticRpcDumpFile$1, t as reviveDumpError$1, u as StaticRpcDumpManifestStaticEntry$1 } from "./index-YDSJgsyG.mjs";
+import { C as RpcFunctionType, S as RpcFunctionSetupResult, T as RpcReturnSchema, _ as RpcFunctionDefinition, i as RpcArgsSchema, v as RpcFunctionDefinitionAny, w as RpcFunctionsCollector } from "./types-CnJSgRVa.mjs";
+import { a as getDefinitionsWithDumps$1, c as StaticRpcDumpManifest$1, d as StaticRpcDumpManifestValue$1, f as StaticRpcDumpSerialization$1, i as dumpFunctions$1, l as StaticRpcDumpManifestQueryEntry$1, n as serializeDumpError$1, o as StaticRpcDumpCollection$1, p as collectStaticRpcDump$1, r as createClientFromDump$1, s as StaticRpcDumpFile$1, t as reviveDumpError$1, u as StaticRpcDumpManifestStaticEntry$1 } from "./index-vAX6bYuc.mjs";
 //#region src/rpc/cache.d.ts
 interface RpcCacheOptions {
   functions: string[];
@@ -94,6 +94,30 @@ declare const STRUCTURED_CLONE_PREFIX = "s:";
  */
 declare function strictJsonStringify(value: unknown, fnName?: string): string;
 //#endregion
+//#region src/rpc/validate-io.d.ts
+/**
+ * Validate positional arguments against their declared schemas. Only
+ * indices with a schema are checked; extra arguments pass through
+ * untouched. Throws `DF0038` on the first failing argument.
+ *
+ * Validation guards the payload without rewriting it: the original values
+ * are handed to the handler unchanged, so a schema that describes a subset
+ * of an object never silently strips the sender's extra fields (and any
+ * declared transforms stay a purely type-level concern).
+ *
+ * @internal
+ */
+declare function validateRpcArgs(name: string, argsSchema: RpcArgsSchema | undefined, args: readonly unknown[]): Promise<unknown[]>;
+/**
+ * Validate a handler's resolved return value against its declared schema.
+ * Throws `DF0039` when the value fails the schema, otherwise returns the
+ * original value unchanged (guard-only, never rewriting the payload — see
+ * {@link validateRpcArgs}). Passes through when no return schema is set.
+ *
+ * @internal
+ */
+declare function validateRpcReturn(name: string, returnSchema: RpcReturnSchema | undefined, value: unknown): Promise<unknown>;
+//#endregion
 //#region src/rpc/validation.d.ts
 /**
  * Validates RPC function definitions.
@@ -137,4 +161,4 @@ type StaticRpcDumpManifestValue = StaticRpcDumpManifestValue$1;
 /** @deprecated Import from `devframe/rpc/dump` instead. */
 type StaticRpcDumpSerialization = StaticRpcDumpSerialization$1;
 //#endregion
-export { RpcCacheManager as C, RpcFunctionsCollectorBase as S, strictJsonStringify as _, StaticRpcDumpManifestStaticEntry as a, createDefineWrapperWithContext as b, collectStaticRpcDump as c, getDefinitionsWithDumps as d, reviveDumpError as f, STRUCTURED_CLONE_PREFIX as g, validateDefinitions as h, StaticRpcDumpManifestQueryEntry as i, createClientFromDump as l, validateDefinition as m, StaticRpcDumpFile as n, StaticRpcDumpManifestValue as o, serializeDumpError as p, StaticRpcDumpManifest as r, StaticRpcDumpSerialization as s, StaticRpcDumpCollection as t, dumpFunctions as u, getRpcHandler as v, RpcCacheOptions as w, defineRpcFunction as x, getRpcResolvedSetupResult as y };
+export { defineRpcFunction as C, RpcCacheOptions as E, createDefineWrapperWithContext as S, RpcCacheManager as T, validateRpcReturn as _, StaticRpcDumpManifestStaticEntry as a, getRpcHandler as b, collectStaticRpcDump as c, getDefinitionsWithDumps as d, reviveDumpError as f, validateRpcArgs as g, validateDefinitions as h, StaticRpcDumpManifestQueryEntry as i, createClientFromDump as l, validateDefinition as m, StaticRpcDumpFile as n, StaticRpcDumpManifestValue as o, serializeDumpError as p, StaticRpcDumpManifest as r, StaticRpcDumpSerialization as s, StaticRpcDumpCollection as t, dumpFunctions as u, STRUCTURED_CLONE_PREFIX as v, RpcFunctionsCollectorBase as w, getRpcResolvedSetupResult as x, strictJsonStringify as y };

package/dist/{index-YDSJgsyG.d.mts → index-vAX6bYuc.d.mts}

@@ -1,4 +1,4 @@
-import { h as RpcDumpStore, l as RpcDumpClientOptions, m as RpcDumpRecordError, n as BirpcReturn, o as RpcDefinitionsToFunctions, u as RpcDumpCollectionOptions, v as RpcFunctionDefinitionAny } from "./types-CrzNxXKq.mjs";
+import { h as RpcDumpStore, l as RpcDumpClientOptions, m as RpcDumpRecordError, n as BirpcReturn, o as RpcDefinitionsToFunctions, u as RpcDumpCollectionOptions, v as RpcFunctionDefinitionAny } from "./types-CnJSgRVa.mjs";
 //#region src/rpc/dump/static.d.ts
 type StaticRpcDumpSerialization = 'json' | 'structured-clone';
 interface StaticRpcDumpManifestStaticEntry {

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as DevframeRpcServerFunctions, A as DevframeSettingsStore, At as EventUnsubscribe, B as DevframeDefineDiagnosticsOptions, C as DevframeServicesHost, Ct as AgentResourceContent, D as DevframeScopedStreamingHost, Dt as DevframeAgentHost, E as DevframeScopedNodeRpc, Et as AgentToolInput, F as ScopedSharedStates, G as RpcBroadcastOptions, H as DevframeDiagnosticsHost, I as SettingsForNamespace, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost, M as ScopedClientFunctions, N as ScopedRpcFn, O as DevframeSettings, Ot as DevframeAgentHostEvents, P as ScopedServerFunctions, Q as DevframeRpcClientFunctions, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, V as DevframeDiagnosticsDefinition, W as DevframeNodeRpcSession, X as RpcStreamingChannelOptions, Y as RpcStreamingChannel, Z as RpcStreamingHost, _ as ConnectionMeta, a as DevframeDockDefaults, b as DevframeNodeContext, bt as AgentHandle, c as DevframeSetupInfo, d as McpRouteOptions, et as DevframeRpcSharedStates, f as defineDevframe, g as Thenable, h as PartialWithoutId, i as DevframeDeploymentKind, j as ScopedBroadcastOptions, jt as EventsMap, k as DevframeSettingsRegistry, kt as EventEmitter, l as DevframeSpaOptions, m as EntriesToObject, n as DevframeCliOptions, o as DevframeDuplicationStrategy, q as RpcSharedStateGetOptions, r as DevframeDefinition, s as DevframeRuntime, t as DevframeBrowserContext, u as DevframeWsOptions, v as ConnectionMetaWebsocket, w as DevframeServicesRegistry, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest, y as DevframeCapabilities, z as DevframeStorageScope } from "./devframe-Ckhf3kFw.mjs";
-import { C as RpcFunctionType, T as RpcReturnSchema, _ as RpcFunctionDefinition, g as RpcFunctionAgentOptions, i as RpcArgsSchema } from "./types-CrzNxXKq.mjs";
-import "./index-DgsLFhZg.mjs";
-import { t as DevframeNodeRpcSessionMeta } from "./ws-server-9-wn7MNQ.mjs";
+import { $ as DevframeRpcServerFunctions, A as DevframeSettingsStore, At as DevframeAgentHostEvents, B as DevframeDefineDiagnosticsOptions, C as DevframeServicesHost, Ct as AgentResourceContent, D as DevframeScopedStreamingHost, Dt as AgentToolProvider, E as DevframeScopedNodeRpc, Et as AgentToolInput, F as ScopedSharedStates, G as RpcBroadcastOptions, H as DevframeDiagnosticsHost, I as SettingsForNamespace, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost, M as ScopedClientFunctions, Mt as EventUnsubscribe, N as ScopedRpcFn, Nt as EventsMap, O as DevframeSettings, Ot as AgentToolProviderHandle, P as ScopedServerFunctions, Q as DevframeRpcClientFunctions, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, V as DevframeDiagnosticsDefinition, W as DevframeNodeRpcSession, X as RpcStreamingChannelOptions, Y as RpcStreamingChannel, Z as RpcStreamingHost, _ as ConnectionMeta, a as DevframeDockDefaults, b as DevframeNodeContext, bt as AgentHandle, c as DevframeSetupInfo, d as McpRouteOptions, et as DevframeRpcSharedStates, f as defineDevframe, g as Thenable, h as PartialWithoutId, i as DevframeDeploymentKind, j as ScopedBroadcastOptions, jt as EventEmitter, k as DevframeSettingsRegistry, kt as DevframeAgentHost, l as DevframeSpaOptions, m as EntriesToObject, n as DevframeCliOptions, o as DevframeDuplicationStrategy, q as RpcSharedStateGetOptions, r as DevframeDefinition, s as DevframeRuntime, t as DevframeBrowserContext, u as DevframeWsOptions, v as ConnectionMetaWebsocket, w as DevframeServicesRegistry, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest, y as DevframeCapabilities, z as DevframeStorageScope } from "./devframe-Dsjn_Xtq.mjs";
+import { C as RpcFunctionType, T as RpcReturnSchema, _ as RpcFunctionDefinition, g as RpcFunctionAgentOptions, i as RpcArgsSchema } from "./types-CnJSgRVa.mjs";
+import "./index-Dbw1p5ch.mjs";
+import { t as DevframeNodeRpcSessionMeta } from "./ws-server-D_Vjtums.mjs";
 //#region src/define.d.ts
 declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>;
 //#endregion
-export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type ConnectionMeta, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeBrowserContext, type DevframeCapabilities, type DevframeCliOptions, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRuntime, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceId, type DevframeServiceOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSpaOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type PartialWithoutId, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedRpcFn, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type Thenable, type defineDevframe, defineRpcFunction };
+export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeBrowserContext, type DevframeCapabilities, type DevframeCliOptions, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRuntime, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceId, type DevframeServiceOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSpaOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type PartialWithoutId, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedRpcFn, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type Thenable, type defineDevframe, defineRpcFunction };

package/dist/instance-registry-D6fxYu36.mjs

@@ -0,0 +1,190 @@
+import { t as diagnostics } from "./diagnostics-B5-qHeqD.mjs";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "pathe";
+import process from "node:process";
+import { homedir } from "node:os";
+//#region src/node/instance-registry.ts
+/** Environment variable overriding the registry directory (tests, CI). */
+const DEVFRAME_INSTANCES_DIR_ENV = "DEVFRAME_INSTANCES_DIR";
+/** Environment variable disabling instance registration entirely. */
+const DEVFRAME_DISABLE_INSTANCE_REGISTRY_ENV = "DEVFRAME_DISABLE_INSTANCE_REGISTRY";
+/**
+* Resolve the registry directory: `~/.devframe/instances/` by default —
+* the framework's own global dir, deliberately outside the per-app
+* `~/.<appName>/devframe/` storage convention since the registry spans apps —
+* overridable via `DEVFRAME_INSTANCES_DIR`.
+*/
+function resolveInstancesDir(override) {
+	return override ?? process.env[DEVFRAME_INSTANCES_DIR_ENV] ?? join(homedir(), ".devframe", "instances");
+}
+function isRegistryDisabled() {
+	const value = process.env[DEVFRAME_DISABLE_INSTANCE_REGISTRY_ENV];
+	return value === "1" || value === "true";
+}
+/**
+* Record a running devframe instance in the global instance registry so
+* discovery tooling (`devframe connect`, editor integrations) can find it
+* without port guessing.
+*
+* `createDevServer` registers automatically; custom hosts that serve a
+* devframe in-process (e.g. `@devframes/next`'s host inside a Next dev
+* server) call this explicitly with the origin they are reachable at.
+*
+* The record is written atomically to `<dir>/<pid>-<port>.json` and removed
+* by {@link DevframeInstanceRegistration.unregister}. Records surviving a
+* crash are pruned by readers whose liveness probe fails. Registration never
+* throws — a write failure degrades to a coded warning (`DF0045`), since a
+* dev server must not die over discovery metadata.
+*
+* @experimental
+*/
+function registerDevframeInstance(record, options = {}) {
+	const dir = resolveInstancesDir(options.instancesDir);
+	const file = join(dir, `${record.pid}-${record.port}.json`);
+	if (!isRegistryDisabled()) try {
+		mkdirSync(dir, { recursive: true });
+		const tmp = join(dir, `.${record.pid}-${record.port}.${Date.now()}.tmp`);
+		writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`);
+		renameSync(tmp, file);
+	} catch (error) {
+		diagnostics.DF0045({
+			file,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+	return {
+		file,
+		unregister: () => {
+			try {
+				rmSync(file, { force: true });
+			} catch (error) {
+				diagnostics.DF0045({
+					file,
+					reason: error instanceof Error ? error.message : String(error),
+					cause: error
+				});
+			}
+		}
+	};
+}
+/**
+* Read every record in the registry directory, dropping unparseable files.
+* Liveness is the caller's concern — see {@link probeDevframeInstance}.
+*
+* @experimental
+*/
+function readDevframeInstances(options = {}) {
+	const dir = resolveInstancesDir(options.instancesDir);
+	let files;
+	try {
+		files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+	} catch {
+		return [];
+	}
+	const records = [];
+	for (const file of files) try {
+		const parsed = JSON.parse(readFileSync(join(dir, file), "utf8"));
+		if (typeof parsed?.origin === "string" && typeof parsed?.pid === "number") records.push(parsed);
+	} catch {}
+	return records;
+}
+/**
+* Dialable-origin candidates for a recorded origin. A `localhost` bind is
+* ambiguous — the server may listen on `127.0.0.1`, `::1`, or both, and
+* HTTP clients differ in which family they try — so probe the explicit
+* addresses too and adopt whichever answers.
+*/
+function originCandidates(origin) {
+	try {
+		const url = new URL(origin);
+		if (url.hostname !== "localhost") return [origin];
+		const port = url.port ? `:${url.port}` : "";
+		return [
+			origin,
+			`${url.protocol}//127.0.0.1${port}`,
+			`${url.protocol}//[::1]${port}`
+		];
+	} catch {
+		return [origin];
+	}
+}
+/**
+* Probe `<origin><basePath>__connection.json`, trying each dialable
+* candidate for the origin (see {@link originCandidates}). The single
+* probe primitive behind both registry liveness checks and the
+* connector's explicit `--port` probes.
+*
+* @internal
+*/
+async function probeDevframeOrigin(origin, basePath, timeoutMs) {
+	const base = basePath.endsWith("/") ? basePath : `${basePath}/`;
+	for (const candidate of originCandidates(origin)) try {
+		const response = await fetch(`${candidate}${base}__connection.json`, { signal: AbortSignal.timeout(timeoutMs ?? 1e3) });
+		if (!response.ok) continue;
+		return {
+			origin: candidate,
+			meta: await response.json().catch(() => ({}))
+		};
+	} catch {}
+	return null;
+}
+/**
+* Probe a record's `__connection.json` to check the instance is alive.
+* Returns the **dialable origin** that answered (for `localhost` records
+* this may be an explicit `127.0.0.1` / `[::1]` origin), or `null` when
+* unreachable.
+*/
+async function probeDevframeInstance(record, options = {}) {
+	return (await probeDevframeOrigin(record.origin, record.basePath, options.timeoutMs))?.origin ?? null;
+}
+/**
+* Read the registry and split records into live and dead by probing each
+* one's `__connection.json`, deleting dead records (prune-on-read). Live
+* records carry the dialable origin the probe confirmed (a `localhost`
+* record may come back as `127.0.0.1` / `[::1]`).
+*
+* A liveness probe only proves *something* answers on the record's port, so
+* records left behind by killed processes shadow the server currently bound
+* there: per `(port, basePath)` only the newest record survives, older
+* ghosts are pruned with the dead.
+*
+* @experimental
+*/
+async function listLiveDevframeInstances(options = {}) {
+	const dir = resolveInstancesDir(options.instancesDir);
+	const records = readDevframeInstances({ instancesDir: dir });
+	const pruned = [];
+	const prune = (record) => {
+		pruned.push(record);
+		try {
+			rmSync(join(dir, `${record.pid}-${record.port}.json`), { force: true });
+		} catch {}
+	};
+	const newest = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const key = `${record.port}|${record.basePath}`;
+		const existing = newest.get(key);
+		if (!existing) newest.set(key, record);
+		else if (record.startedAt > existing.startedAt) {
+			prune(existing);
+			newest.set(key, record);
+		} else prune(record);
+	}
+	const live = [];
+	await Promise.all([...newest.values()].map(async (record) => {
+		const origin = await probeDevframeInstance(record, options);
+		if (origin) live.push(origin === record.origin ? record : {
+			...record,
+			origin
+		});
+		else prune(record);
+	}));
+	live.sort((a, b) => a.startedAt - b.startedAt);
+	return {
+		live,
+		pruned
+	};
+}
+//#endregion
+export { probeDevframeOrigin as n, registerDevframeInstance as r, listLiveDevframeInstances as t };

package/dist/node/auth.d.mts

@@ -1,3 +1,3 @@
-import { p as DevframeAuthHandler } from "../devframe-Ckhf3kFw.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-8dndvIxR.mjs";
+import { p as DevframeAuthHandler } from "../devframe-Dsjn_Xtq.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-CeBbry0R.mjs";
 export { DevframeAuthHandler, buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, refreshTempAuthCode, revokeActiveConnectionsForToken, revokeAuthToken, verifyAuthToken };

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

@@ -1,5 +1,5 @@
-import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-Ckhf3kFw.mjs";
-import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-CzqPrJSz.mjs";
+import { i as DevframeDeploymentKind, r as DevframeDefinition } from "../devframe-Dsjn_Xtq.mjs";
+import { a as internalContextMap, i as getInternalContext, n as InternalAnonymousAuthStorage, r as RemoteTokenRecord, t as DevframeInternalContext } from "../context-7BbaIUSI.mjs";
 //#region src/adapters/_shared.d.ts
 /**
  * Resolve the mount base path for a devframe's SPA. Hosted adapters

package/dist/node/hub-internals.mjs

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

package/dist/node/index.d.mts

@@ -1,8 +1,38 @@
-import { C as DevframeServicesHost, Ct as AgentResourceContent, Dt as DevframeAgentHost$1, Et as AgentToolInput, H as DevframeDiagnosticsHost$1, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost$1, O as DevframeSettings, Ot as DevframeAgentHostEvents, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, Z as RpcStreamingHost, b as DevframeNodeContext, bt as AgentHandle, ht as SharedState, kt as EventEmitter, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest } from "../devframe-Ckhf3kFw.mjs";
-import { v as RpcFunctionDefinitionAny } from "../types-CrzNxXKq.mjs";
-import "../index-DgsLFhZg.mjs";
-import { n as StartedServer, r as startHttpAndWs, t as StartHttpAndWsOptions } from "../server-B0wiP_Oi.mjs";
+import { At as DevframeAgentHostEvents, C as DevframeServicesHost, Ct as AgentResourceContent, Dt as AgentToolProvider, Et as AgentToolInput, H as DevframeDiagnosticsHost$1, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost$1, O as DevframeSettings, Ot as AgentToolProviderHandle, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, Z as RpcStreamingHost, b as DevframeNodeContext, bt as AgentHandle, ht as SharedState, jt as EventEmitter, kt as DevframeAgentHost$1, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest } from "../devframe-Dsjn_Xtq.mjs";
+import { v as RpcFunctionDefinitionAny } from "../types-CnJSgRVa.mjs";
+import "../index-Dbw1p5ch.mjs";
+import { n as StartedServer, r as startHttpAndWs, t as StartHttpAndWsOptions } from "../server-VLQJouOO.mjs";
 import { BirpcGroup } from "birpc";
+//#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/context.d.ts
 interface CreateHostContextOptions {
   cwd: string;
@@ -40,10 +70,12 @@ declare class DevframeAgentHost implements DevframeAgentHost$1 {
   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;
@@ -55,9 +87,10 @@ declare class DevframeAgentHost implements DevframeAgentHost$1 {
   _dispose(): void;
   private _validateToolId;
   private _projectTool;
+  /** Query every registered provider, projecting inputs to serializable tools. */
+  private _collectProviderTools;
   private _collectRpcTools;
   private _findRpcDefinition;
-  private _coercePositionalArgs;
 }
 //#endregion
 //#region src/node/host-diagnostics.d.ts
@@ -135,6 +168,71 @@ declare class DevframeViewHost implements DevframeViewHost$1 {
   hostStatic(baseUrl: string, distDir: string): void;
 }
 //#endregion
+//#region src/node/instance-registry.d.ts
+/**
+ * One running devframe instance, as recorded in the instance registry.
+ * Records are self-describing JSON — additive fields are safe.
+ *
+ * @experimental The agent-native surface is experimental and may change
+ * without a major version bump until it stabilizes.
+ */
+interface DevframeInstanceRecord {
+  /** Process id of the dev server. */
+  pid: number;
+  /** Listening port. */
+  port: number;
+  /** Dialable HTTP origin, e.g. `http://127.0.0.1:9876`. */
+  origin: string;
+  /** Base path the devframe is mounted at (trailing slash). */
+  basePath: string;
+  /** Definition id. */
+  id: string;
+  /** Definition display name. */
+  name?: string;
+  /** Working directory the instance was started from. */
+  rootDir: string;
+  /**
+   * Absolute URL path of the MCP Streamable-HTTP endpoint on `origin`, or
+   * `null` when the instance runs without an MCP route.
+   */
+  mcp: {
+    path: string;
+  } | null;
+  /** Epoch-ms timestamp of registration. */
+  startedAt: number;
+}
+/**
+ * Handle returned by {@link registerDevframeInstance}.
+ *
+ * @experimental
+ */
+interface DevframeInstanceRegistration {
+  /** The registry file backing this registration. */
+  readonly file: string;
+  /** Remove the record (idempotent). Call on server close. */
+  unregister: () => void;
+}
+/**
+ * Record a running devframe instance in the global instance registry so
+ * discovery tooling (`devframe connect`, editor integrations) can find it
+ * without port guessing.
+ *
+ * `createDevServer` registers automatically; custom hosts that serve a
+ * devframe in-process (e.g. `@devframes/next`'s host inside a Next dev
+ * server) call this explicitly with the origin they are reachable at.
+ *
+ * The record is written atomically to `<dir>/<pid>-<port>.json` and removed
+ * by {@link DevframeInstanceRegistration.unregister}. Records surviving a
+ * crash are pruned by readers whose liveness probe fails. Registration never
+ * throws — a write failure degrades to a coded warning (`DF0045`), since a
+ * dev server must not die over discovery metadata.
+ *
+ * @experimental
+ */
+declare function registerDevframeInstance(record: DevframeInstanceRecord, options?: {
+  instancesDir?: string;
+}): DevframeInstanceRegistration;
+//#endregion
 //#region src/node/rpc-shared-state.d.ts
 declare function createRpcSharedStateServerHost(rpc: RpcFunctionsHost): RpcSharedStateHost;
 //#endregion
@@ -180,4 +278,4 @@ declare function toDialableHost(host: string): string;
 declare function formatHostForUrl(host: string): string;
 declare function normalizeHttpServerUrl(host: string, port: number | string): string;
 //#endregion
-export { CreateH3DevframeHostOptions, CreateHostContextOptions, CreateStorageOptions, DevframeAgentHost, DevframeDiagnosticsHost, DevframeServicesHostImpl, DevframeViewHost, type RpcFunctionsHost, StartHttpAndWsOptions, StartedServer, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, normalizeHttpServerUrl, startHttpAndWs, toDialableHost };
+export { AgentArgsFallback, CreateH3DevframeHostOptions, CreateHostContextOptions, CreateStorageOptions, DevframeAgentHost, DevframeDiagnosticsHost, type DevframeInstanceRecord, type DevframeInstanceRegistration, DevframeServicesHostImpl, DevframeViewHost, type RpcFunctionsHost, StartHttpAndWsOptions, StartedServer, coerceAgentPositionalArgs, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, normalizeHttpServerUrl, registerDevframeInstance, startHttpAndWs, toDialableHost };

package/dist/node/index.mjs

@@ -1,4 +1,5 @@
-import { t as createStorage } from "../storage-gEnj9ASQ.mjs";
-import { a as DevframeViewHost, c as createRpcSharedStateServerHost, i as createNodeSettings, l as DevframeDiagnosticsHost, n as createHostContext, o as DevframeServicesHostImpl, r as createScopedNodeContext, s as createRpcStreamingServerHost, t as createH3DevframeHost, u as DevframeAgentHost } from "../host-h3-CgOetlNE.mjs";
-import { a as toDialableHost, i as normalizeHttpServerUrl, n as formatHostForUrl, r as isObject, t as startHttpAndWs } from "../server-DykHCza_.mjs";
-export { DevframeAgentHost, DevframeDiagnosticsHost, DevframeServicesHostImpl, DevframeViewHost, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, normalizeHttpServerUrl, startHttpAndWs, toDialableHost };
+import { a as DevframeViewHost, c as createRpcSharedStateServerHost, d as coerceAgentPositionalArgs, i as createNodeSettings, l as DevframeDiagnosticsHost, n as createHostContext, o as DevframeServicesHostImpl, r as createScopedNodeContext, s as createRpcStreamingServerHost, t as createH3DevframeHost, u as DevframeAgentHost } from "../host-h3-Kz7t5Xab.mjs";
+import { t as createStorage } from "../storage-Dzoc3NVC.mjs";
+import { r as registerDevframeInstance } from "../instance-registry-D6fxYu36.mjs";
+import { a as toDialableHost, i as normalizeHttpServerUrl, n as formatHostForUrl, r as isObject, t as startHttpAndWs } from "../server-CcAPxuoT.mjs";
+export { DevframeAgentHost, DevframeDiagnosticsHost, DevframeServicesHostImpl, DevframeViewHost, coerceAgentPositionalArgs, createH3DevframeHost, createHostContext, createNodeSettings, createRpcSharedStateServerHost, createRpcStreamingServerHost, createScopedNodeContext, createStorage, formatHostForUrl, isObject, normalizeHttpServerUrl, registerDevframeInstance, startHttpAndWs, toDialableHost };

package/dist/recipes/common-rpc-functions.d.mts

@@ -1,7 +1,7 @@
-import "../devframe-Ckhf3kFw.mjs";
-import { E as Thenable, S as RpcFunctionSetupResult, c as RpcDump, g as RpcFunctionAgentOptions } from "../types-CrzNxXKq.mjs";
-import "../index-DgsLFhZg.mjs";
-import * as v from "valibot";
+import "../devframe-Dsjn_Xtq.mjs";
+import { E as Thenable, S as RpcFunctionSetupResult, c as RpcDump, g as RpcFunctionAgentOptions } from "../types-CnJSgRVa.mjs";
+import "../index-Dbw1p5ch.mjs";
+import { t as SimpleSchema } from "../simple-schema-BDzLeJDk.mjs";
 //#region src/recipes/common-rpc-functions.d.ts
 /**
  * Editor commands that `launch-editor` (the library behind
@@ -11,7 +11,7 @@ import * as v from "valibot";
  * arbitrary command.
  */
 type KnownEditor = 'atom' | 'subl' | 'sublime' | 'sublime_text' | 'wstorm' | 'charm' | 'zed' | 'notepad++' | 'vim' | 'mvim' | 'joe' | 'gvim' | 'emacs' | 'emacsclient' | 'rmate' | 'mate' | 'code' | 'code-insiders' | 'codium' | 'vscodium' | 'trae' | 'antigravity' | 'cursor' | 'appcode' | 'clion' | 'idea' | 'phpstorm' | 'pycharm' | 'rubymine' | 'webstorm' | 'goland' | 'rider';
-/** Runtime list of every {@link KnownEditor}, in the order `v.picklist` reports them. */
+/** Runtime list of every {@link KnownEditor}. */
 declare const KNOWN_EDITORS: KnownEditor[];
 /**
  * Prebuilt RPC action that opens a file in the user's configured editor.
@@ -38,16 +38,16 @@ declare const openInEditor: {
   name: "devframe:open-in-editor";
   type?: "action" | undefined;
   cacheable?: boolean;
-  args: readonly [v.StringSchema<undefined>, v.OptionalSchema<v.PicklistSchema<KnownEditor[], undefined>, undefined>];
-  returns: v.VoidSchema<undefined>;
+  args: readonly [SimpleSchema<string, string>, SimpleSchema<KnownEditor | undefined, KnownEditor | undefined>];
+  returns: SimpleSchema<void, void>;
   jsonSerializable?: boolean;
   agent?: RpcFunctionAgentOptions;
-  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>>) | undefined;
-  handler?: ((args_0: string, args_1: KnownEditor | undefined) => void) | undefined;
-  dump?: RpcDump<[string, KnownEditor | undefined], void, undefined> | undefined;
+  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>>) | undefined;
+  handler?: ((args_0: string, args_1: KnownEditor | undefined) => Thenable<void>) | undefined;
+  dump?: RpcDump<[string, KnownEditor | undefined], Thenable<void>, undefined> | undefined;
   snapshot?: boolean;
-  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>>> | undefined;
-  __promise?: Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>> | undefined;
+  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>>> | undefined;
+  __promise?: Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>> | undefined;
 };
 /**
  * Prebuilt RPC action that reveals a path in the OS file explorer.
@@ -64,16 +64,16 @@ declare const openInFinder: {
   name: "devframe:open-in-finder";
   type?: "action" | undefined;
   cacheable?: boolean;
-  args: readonly [v.StringSchema<undefined>];
-  returns: v.VoidSchema<undefined>;
+  args: readonly [SimpleSchema<string, string>];
+  returns: SimpleSchema<void, void>;
   jsonSerializable?: boolean;
   agent?: RpcFunctionAgentOptions;
-  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string], void>>) | undefined;
-  handler?: ((args_0: string) => void) | undefined;
-  dump?: RpcDump<[string], void, undefined> | undefined;
+  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string], Thenable<void>>>) | undefined;
+  handler?: ((args_0: string) => Thenable<void>) | undefined;
+  dump?: RpcDump<[string], Thenable<void>, undefined> | undefined;
   snapshot?: boolean;
-  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string], void>>> | undefined;
-  __promise?: Thenable<RpcFunctionSetupResult<[string], void>> | undefined;
+  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string], Thenable<void>>>> | undefined;
+  __promise?: Thenable<RpcFunctionSetupResult<[string], Thenable<void>>> | undefined;
 };
 /**
  * Convenience array bundling both helpers so callers can register them
@@ -89,30 +89,30 @@ declare const commonRpcFunctions: readonly [{
   name: "devframe:open-in-editor";
   type?: "action" | undefined;
   cacheable?: boolean;
-  args: readonly [v.StringSchema<undefined>, v.OptionalSchema<v.PicklistSchema<KnownEditor[], undefined>, undefined>];
-  returns: v.VoidSchema<undefined>;
+  args: readonly [SimpleSchema<string, string>, SimpleSchema<KnownEditor | undefined, KnownEditor | undefined>];
+  returns: SimpleSchema<void, void>;
   jsonSerializable?: boolean;
   agent?: RpcFunctionAgentOptions;
-  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>>) | undefined;
-  handler?: ((args_0: string, args_1: KnownEditor | undefined) => void) | undefined;
-  dump?: RpcDump<[string, KnownEditor | undefined], void, undefined> | undefined;
+  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>>) | undefined;
+  handler?: ((args_0: string, args_1: KnownEditor | undefined) => Thenable<void>) | undefined;
+  dump?: RpcDump<[string, KnownEditor | undefined], Thenable<void>, undefined> | undefined;
   snapshot?: boolean;
-  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>>> | undefined;
-  __promise?: Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], void>> | undefined;
+  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>>> | undefined;
+  __promise?: Thenable<RpcFunctionSetupResult<[string, KnownEditor | undefined], Thenable<void>>> | undefined;
 }, {
   name: "devframe:open-in-finder";
   type?: "action" | undefined;
   cacheable?: boolean;
-  args: readonly [v.StringSchema<undefined>];
-  returns: v.VoidSchema<undefined>;
+  args: readonly [SimpleSchema<string, string>];
+  returns: SimpleSchema<void, void>;
   jsonSerializable?: boolean;
   agent?: RpcFunctionAgentOptions;
-  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string], void>>) | undefined;
-  handler?: ((args_0: string) => void) | undefined;
-  dump?: RpcDump<[string], void, undefined> | undefined;
+  setup?: ((context: undefined) => Thenable<RpcFunctionSetupResult<[string], Thenable<void>>>) | undefined;
+  handler?: ((args_0: string) => Thenable<void>) | undefined;
+  dump?: RpcDump<[string], Thenable<void>, undefined> | undefined;
   snapshot?: boolean;
-  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string], void>>> | undefined;
-  __promise?: Thenable<RpcFunctionSetupResult<[string], void>> | undefined;
+  __cache?: WeakMap<object, Thenable<RpcFunctionSetupResult<[string], Thenable<void>>>> | undefined;
+  __promise?: Thenable<RpcFunctionSetupResult<[string], Thenable<void>>> | undefined;
 }];
 //#endregion
 export { KNOWN_EDITORS, KnownEditor, commonRpcFunctions, openInEditor, openInFinder };

package/dist/recipes/common-rpc-functions.mjs

@@ -1,7 +1,7 @@
 import { n as defineRpcFunction } from "../define-BLWPsH6y.mjs";
-import * as v from "valibot";
+import { t as s } from "../simple-schema-DQPZrAaZ.mjs";
 //#region src/recipes/common-rpc-functions.ts
-/** Runtime list of every {@link KnownEditor}, in the order `v.picklist` reports them. */
+/** Runtime list of every {@link KnownEditor}. */
 const KNOWN_EDITORS = [
 	"atom",
 	"subl",
@@ -61,8 +61,8 @@ const openInEditor = defineRpcFunction({
 	name: "devframe:open-in-editor",
 	type: "action",
 	jsonSerializable: true,
-	args: [v.string(), v.optional(v.picklist(KNOWN_EDITORS))],
-	returns: v.void(),
+	args: [s.string(), s.optional(s.picklist(KNOWN_EDITORS))],
+	returns: s.void(),
 	async handler(filename, editor) {
 		const { launchEditor } = await import("../utils/launch-editor.mjs");
 		launchEditor(filename, editor);
@@ -83,8 +83,8 @@ const openInFinder = defineRpcFunction({
 	name: "devframe:open-in-finder",
 	type: "action",
 	jsonSerializable: true,
-	args: [v.string()],
-	returns: v.void(),
+	args: [s.string()],
+	returns: s.void(),
 	async handler(path) {
 		const { open } = await import("../utils/open.mjs");
 		await open(path);

package/dist/recipes/interactive-auth.d.mts

@@ -1,5 +1,5 @@
-import { b as DevframeNodeContext, p as DevframeAuthHandler } from "../devframe-Ckhf3kFw.mjs";
-import "../index-8dndvIxR.mjs";
+import { b as DevframeNodeContext, p as DevframeAuthHandler } from "../devframe-Dsjn_Xtq.mjs";
+import "../index-CeBbry0R.mjs";
 //#region src/recipes/interactive-auth.d.ts
 interface CreateInteractiveAuthOptions {
   /**