devframe 1.2.6 → 1.3.0

package/dist/{context-dOWXVHc6.d.mts → context-Dko5QFWF.d.mts}

@@ -373,6 +373,187 @@ interface DevframeAuthHandler {
   buildOpenUrl?: (url: string) => string;
 }
 //#endregion
+//#region src/types/mcp.d.ts
+/**
+ * The MCP adapter surface, typed here so `devframe` (which probes for and
+ * lazily loads `@devframes/agentic`) and `@devframes/agentic/mcp` (which
+ * implements it) share one contract without a type-level dependency cycle.
+ * None of these shapes reference the MCP SDK: the SDK is an implementation
+ * detail of `@devframes/agentic`, freely swappable behind this surface.
+ * The h3-bound `mountMcpHttp` shapes live in `node/agentic.ts` (exported via
+ * `devframe/internal`) instead: `devframe/types` must stay lib-neutral, and
+ * h3's declarations are not.
+ */
+interface CreateMcpServerOptions {
+  /**
+   * Transport to use. `createMcpServer` itself runs `'stdio'` (a standalone
+   * process with its own host context); the Streamable-HTTP transport is
+   * served route-based by the dev server instead; see `mountMcpHttp` and
+   * the `mcp` option on `createDevServer` / `createCac`'s `--mcp` flag.
+   */
+  transport?: 'stdio';
+  /**
+   * Expose shared-state keys as MCP resources.
+   * - `true` (default): every key the host publishes
+   * - `false`: none
+   * - `(key) => boolean`: filter
+   */
+  exposeSharedState?: boolean | ((key: string) => boolean);
+  /**
+   * Usage guidance sent as `instructions` in the MCP `initialize` (and
+   * `server/discover`) result. Omitted or empty sends no instructions.
+   */
+  instructions?: string;
+  /**
+   * Resource templates served through `resources/templates/list`, and read
+   * through `resources/read`. Omitted or empty keeps the resources unchanged.
+   */
+  resourceTemplates?: McpResourceTemplate[];
+  /**
+   * Host subscription for resource-list changes; each `notify()` sends
+   * `notifications/resources/list_changed`. See {@link McpResourcesChangedHook}.
+   */
+  onResourcesChanged?: McpResourcesChangedHook;
+  /** Override the name reported in the MCP handshake. */
+  serverName?: string;
+  /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
+  serverVersion?: string;
+  /** Called once the transport is connected. */
+  onReady?: (info: {
+    transport: 'stdio';
+  }) => void;
+}
+/**
+ * One MCP content block in a tool result. Attach blocks to a tool's return
+ * value with `withMcpContent` (from `devframe`) to send them in place of the
+ * default JSON text block. `data` is base64.
+ */
+type McpContentBlock = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'image';
+  data: string;
+  mimeType: string;
+} | {
+  type: 'audio';
+  data: string;
+  mimeType: string;
+};
+interface McpServerHandle {
+  stop: () => Promise<void>;
+}
+interface CreateMcpFetchHandlerOptions {
+  /** Name reported in the MCP handshake. */
+  serverName: string;
+  /** Version reported in the MCP handshake. */
+  serverVersion: string;
+  /** Expose shared-state keys as MCP resources; see {@link CreateMcpServerOptions.exposeSharedState}. */
+  exposeSharedState: boolean | ((key: string) => boolean);
+  /** Usage guidance for the handshake; see {@link CreateMcpServerOptions.instructions}. */
+  instructions?: string;
+  /** Resource templates; see {@link CreateMcpServerOptions.resourceTemplates}. */
+  resourceTemplates?: McpResourceTemplate[];
+  /** Host subscription for resource-list changes; see {@link CreateMcpServerOptions.onResourcesChanged}. */
+  onResourcesChanged?: McpResourcesChangedHook;
+  /**
+   * Optional identity check, layered on top of the origin gate and checked
+   * **after** it: a bearer token string (matched in constant time against
+   * `Authorization: Bearer <token>`), a `(request) => boolean` callback, or
+   * `false` (the default) for origin-only, trusting same-machine callers. A
+   * callback governs identity only and cannot relax the origin gate. See
+   * {@link McpAuthorization}.
+   */
+  authorization?: McpAuthorization;
+  /**
+   * Origin allow-list beyond the loopback default. `false` disables the
+   * origin gate entirely. Default: loopback-only.
+   *
+   * Unlike the WS transport, the MCP route does **not** allow `Origin`-less
+   * requests: a route-based endpoint is reachable by any local process, so a
+   * request must carry an `Origin` that passes the gate. Native clients
+   * (e.g. `devframe connect`) send their loopback origin explicitly.
+   */
+  allowedOrigins?: readonly string[] | false;
+}
+/** Connection facts a host knows about a request beyond the `Request` itself. */
+interface McpConnectionInfo {
+  /**
+   * The connecting peer's remote address (a node socket's `remoteAddress`),
+   * used to prove a same-machine caller when the endpoint relies on the
+   * loopback origin default with no identity check. A host that can resolve a
+   * trustworthy peer address (the h3/node mount) supplies it; when it's
+   * omitted the origin gate stays the only locality signal.
+   */
+  remoteAddress?: string;
+}
+interface McpFetchHandler {
+  /**
+   * WHATWG-`fetch` handler for the MCP endpoint. Hand every method
+   * (POST/GET/DELETE) on the endpoint's path to it; routing by path is the
+   * host's job. Pass {@link McpConnectionInfo} when the host can resolve the
+   * peer address so the default trust boundary can enforce same-machine
+   * locality.
+   */
+  fetch: (request: Request, connection?: McpConnectionInfo) => Promise<Response>;
+  /** Tear down the handler (aborts in-flight exchanges, drops the change bridge). */
+  dispose: () => Promise<void>;
+}
+/** One concrete resource that an {@link McpResourceTemplate} lists in `resources/list`. */
+interface McpResourceTemplateEntry {
+  /** The resource URI. It SHOULD match the `uriTemplate` of its template, so `resources/read` finds it. */
+  uri: string;
+  name: string;
+  /** Human-readable name for display. */
+  title?: string;
+  description?: string;
+  /** Defaults to the `mimeType` of the template. */
+  mimeType?: string;
+}
+/**
+ * What an {@link McpResourceTemplate} returns from `read`, sent as the
+ * `resources/read` result: `text` as is, or else `json` as JSON text.
+ */
+interface McpResourceTemplateContent {
+  text?: string;
+  json?: unknown;
+  /** Defaults to the `mimeType` of the template, then `application/json`. */
+  mimeType?: string;
+}
+/**
+ * A resource template the MCP server lists in `resources/templates/list` and
+ * reads in `resources/read`. The `uriTemplate` uses RFC 6570 level 1 only:
+ * plain `{name}` expressions, with text between any two of them. Each
+ * expression matches a non-empty value with no `/`, and its value is
+ * percent-decoded.
+ *
+ * `list` and `read` get the node context of the devframe (or of the hub), so
+ * they can read live state such as `ctx.rpc.sharedState` or `ctx.agent`. The
+ * route options are resolved before `setup()` runs, so a template cannot
+ * capture that context in a closure.
+ */
+interface McpResourceTemplate {
+  /** RFC 6570 level 1 URI template, e.g. `my-tool://file/{path}`. Anything else throws `DF0084`. */
+  uriTemplate: string;
+  name: string;
+  /** Human-readable name for display. */
+  title?: string;
+  description?: string;
+  /** MIME type of every resource the template stands for. */
+  mimeType?: string;
+  /** The concrete resources the template stands for right now. They are added to `resources/list`. */
+  list?: (ctx: DevframeNodeContext) => McpResourceTemplateEntry[] | Promise<McpResourceTemplateEntry[]>;
+  /** Read one resource: `params` holds the decoded value of each `{name}`, `uri` the requested URI. */
+  read: (params: Record<string, string>, uri: string, ctx: DevframeNodeContext) => McpResourceTemplateContent | Promise<McpResourceTemplateContent>;
+}
+/**
+ * A host subscription for resource-list changes. Call `notify()` each time
+ * the resources change; the MCP server then sends
+ * `notifications/resources/list_changed`. Return a function that removes the
+ * subscription; the MCP server calls it on teardown.
+ */
+type McpResourcesChangedHook = (notify: () => void, ctx: DevframeNodeContext) => () => void;
+//#endregion
 //#region src/types/diagnostics.d.ts
 /**
  * The shared diagnostics lookup exposed by the host. A `Proxy` that resolves
@@ -509,6 +690,13 @@ interface BrowserAgentToolManifest {
   tags?: readonly string[];
   inputSchema?: unknown;
 }
+/** What a connected document reports about itself alongside its tool manifest. */
+interface BrowserAgentClientInfo {
+  url: string;
+  title: string;
+  visible: boolean;
+  focused: boolean;
+}
 //#endregion
 //#region src/types/rpc-augments.d.ts
 /**
@@ -573,7 +761,7 @@ interface DevframeRpcServerFunctions {
   /** Methods eligible for automatic client caching. @internal */
   'devframe:rpc:cacheable-functions': () => Promise<string[]>;
   /** Replace this connection's browser-agent tool manifest, tagged with the calling tab's stable client id. @internal */
-  'devframe:agent:sync-client-tools': (clientId: string, tools: BrowserAgentToolManifest[]) => Promise<void>;
+  'devframe:agent:sync-client-tools': (clientId: string, tools: BrowserAgentToolManifest[], info: BrowserAgentClientInfo) => Promise<void>;
   /**
    * Authenticate a connection with a previously-issued bearer token; resolves
    * whether the connection is now trusted. The interactive handler is provided
@@ -809,8 +997,8 @@ interface DevframeSettingsStore<T extends Record<string, any> = Record<string, a
 /**
  * The two settings scopes available on a scoped context.
  *
- *   - `project`: per-workspace state, persisted under the host's
- *     `workspace` storage dir. Project-local settings.
+ *   - `project`: per-checkout state, persisted under the
+ *     `project` storage dir. Project-local settings.
  *   - `global`:  per-user state, persisted under the host's `global`
  *     storage dir. Machine-wide preferences.
  */
@@ -1296,6 +1484,23 @@ interface McpRouteOptions {
    * Omitted or empty sends no instructions.
    */
   instructions?: string;
+  /**
+   * Resource templates the route serves through MCP
+   * `resources/templates/list`. `resources/read` tries them after the
+   * registered resources and the shared-state resources (a
+   * `devframe://resource/` or `devframe://state/` URI never reaches them);
+   * the first template whose `uriTemplate` matches the URI reads it. `resources/list` adds the
+   * entries each template's `list` returns. Omitted or empty keeps the
+   * resources unchanged.
+   */
+  resourceTemplates?: McpResourceTemplate[];
+  /**
+   * Host subscription for resource-list changes. Call `notify()` each time
+   * the resources change (for example, the entries of a resource template);
+   * the route then sends `notifications/resources/list_changed`. Return a
+   * function that removes the subscription; the route calls it on teardown.
+   */
+  onResourcesChanged?: McpResourcesChangedHook;
 }
 interface DevframeCliOptions {
   /** Binary name; default: the devframe's `id`. */
@@ -1597,119 +1802,6 @@ type DevframeSnapshotRpcEntry = string | {
   inputs: DevframeSnapshotRpcInputs;
 };
 //#endregion
-//#region src/types/mcp.d.ts
-/**
- * The MCP adapter surface, typed here so `devframe` (which probes for and
- * lazily loads `@devframes/agentic`) and `@devframes/agentic/mcp` (which
- * implements it) share one contract without a type-level dependency cycle.
- * None of these shapes reference the MCP SDK: the SDK is an implementation
- * detail of `@devframes/agentic`, freely swappable behind this surface.
- * The h3-bound `mountMcpHttp` shapes live in `node/agentic.ts` (exported via
- * `devframe/internal`) instead: `devframe/types` must stay lib-neutral, and
- * h3's declarations are not.
- */
-interface CreateMcpServerOptions {
-  /**
-   * Transport to use. `createMcpServer` itself runs `'stdio'` (a standalone
-   * process with its own host context); the Streamable-HTTP transport is
-   * served route-based by the dev server instead; see `mountMcpHttp` and
-   * the `mcp` option on `createDevServer` / `createCac`'s `--mcp` flag.
-   */
-  transport?: 'stdio';
-  /**
-   * Expose shared-state keys as MCP resources.
-   * - `true` (default): every key the host publishes
-   * - `false`: none
-   * - `(key) => boolean`: filter
-   */
-  exposeSharedState?: boolean | ((key: string) => boolean);
-  /**
-   * Usage guidance sent as `instructions` in the MCP `initialize` (and
-   * `server/discover`) result. Omitted or empty sends no instructions.
-   */
-  instructions?: string;
-  /** Override the name reported in the MCP handshake. */
-  serverName?: string;
-  /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
-  serverVersion?: string;
-  /** Called once the transport is connected. */
-  onReady?: (info: {
-    transport: 'stdio';
-  }) => void;
-}
-/**
- * One MCP content block in a tool result. Attach blocks to a tool's return
- * value with `withMcpContent` (from `devframe`) to send them in place of the
- * default JSON text block. `data` is base64.
- */
-type McpContentBlock = {
-  type: 'text';
-  text: string;
-} | {
-  type: 'image';
-  data: string;
-  mimeType: string;
-} | {
-  type: 'audio';
-  data: string;
-  mimeType: string;
-};
-interface McpServerHandle {
-  stop: () => Promise<void>;
-}
-interface CreateMcpFetchHandlerOptions {
-  /** Name reported in the MCP handshake. */
-  serverName: string;
-  /** Version reported in the MCP handshake. */
-  serverVersion: string;
-  /** Expose shared-state keys as MCP resources; see {@link CreateMcpServerOptions.exposeSharedState}. */
-  exposeSharedState: boolean | ((key: string) => boolean);
-  /** Usage guidance for the handshake; see {@link CreateMcpServerOptions.instructions}. */
-  instructions?: string;
-  /**
-   * Optional identity check, layered on top of the origin gate and checked
-   * **after** it: a bearer token string (matched in constant time against
-   * `Authorization: Bearer <token>`), a `(request) => boolean` callback, or
-   * `false` (the default) for origin-only, trusting same-machine callers. A
-   * callback governs identity only and cannot relax the origin gate. See
-   * {@link McpAuthorization}.
-   */
-  authorization?: McpAuthorization;
-  /**
-   * Origin allow-list beyond the loopback default. `false` disables the
-   * origin gate entirely. Default: loopback-only.
-   *
-   * Unlike the WS transport, the MCP route does **not** allow `Origin`-less
-   * requests: a route-based endpoint is reachable by any local process, so a
-   * request must carry an `Origin` that passes the gate. Native clients
-   * (e.g. `devframe connect`) send their loopback origin explicitly.
-   */
-  allowedOrigins?: readonly string[] | false;
-}
-/** Connection facts a host knows about a request beyond the `Request` itself. */
-interface McpConnectionInfo {
-  /**
-   * The connecting peer's remote address (a node socket's `remoteAddress`),
-   * used to prove a same-machine caller when the endpoint relies on the
-   * loopback origin default with no identity check. A host that can resolve a
-   * trustworthy peer address (the h3/node mount) supplies it; when it's
-   * omitted the origin gate stays the only locality signal.
-   */
-  remoteAddress?: string;
-}
-interface McpFetchHandler {
-  /**
-   * WHATWG-`fetch` handler for the MCP endpoint. Hand every method
-   * (POST/GET/DELETE) on the endpoint's path to it; routing by path is the
-   * host's job. Pass {@link McpConnectionInfo} when the host can resolve the
-   * peer address so the default trust boundary can enforce same-machine
-   * locality.
-   */
-  fetch: (request: Request, connection?: McpConnectionInfo) => Promise<Response>;
-  /** Tear down the handler (aborts in-flight exchanges, drops the change bridge). */
-  dispose: () => Promise<void>;
-}
-//#endregion
 //#region src/utils/shared-state.d.ts
 type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
 type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
@@ -2311,4 +2403,4 @@ interface ConnectionMeta {
  */
 interface DevframeConnectionConfigsRegistry {}
 //#endregion
-export { McpSetting as $, SharedStateEvents as A, DevframeDiagnosticsLogger as At, DevframeCliOptions as B, AgentResourceInput as Bt, createStreamSink as C, DevframeViewHost as Ct, ImmutableObject as D, DevframeHost as Dt, ImmutableMap as E, DevframeRpcSharedStates as Et, CreateMcpServerOptions as F, parseCliFlags as Ft, DevframeRpcOptions as G, DevframeAgentHost as Gt, DevframeDeploymentKind as H, AgentToolInput as Ht, McpConnectionInfo as I, AgentHandle as It, DevframeSnapshotRpcInputs as J, EventUnsubscribe as Jt, DevframeSetupInfo as K, DevframeAgentHostEvents as Kt, McpContentBlock as L, AgentManifest as Lt, SharedStatePatch as M, CliFlagsSchema as Mt, createSharedState as N, InferCliFlags as Nt, ImmutableSet as O, DevframeStorageScope as Ot, CreateMcpFetchHandlerOptions as P, defineCliFlags as Pt, McpRouteOptions as Q, McpFetchHandler as R, AgentResource as Rt, createStreamReader as S, SettingsForNamespace as St, ImmutableArray as T, DevframeRpcServerFunctions as Tt, DevframeDockDefaults as U, AgentToolProvider as Ut, DevframeDefinition as V, AgentTool as Vt, DevframeDuplicationStrategy as W, AgentToolProviderHandle as Wt, DevframeWsOptions as X, DevframeSseOptions as Y, EventsMap as Yt, McpAuthorization as Z, CreateStreamSinkOptions as _, ScopedBroadcastOptions as _t, DevframeConnectionConfigsRegistry as a, DevframeServiceOf as at, StreamSink as b, ScopedServerFunctions as bt, RpcBroadcastOptions as c, DevframeServicesRegistry as ct, RpcSharedStateHost as d, DevframeScopedNodeContext as dt, DevframeServiceDefinition as et, RpcStreamingChannel as f, DevframeScopedNodeRpc as ft, CreateStreamReaderOptions as g, DevframeSettingsStore as gt, BufferedChunk as h, DevframeSettingsRegistry as ht, DevframeCapabilities as i, DevframeServiceMeta as it, SharedStateOptions as j, DevframeAuthHandler as jt, SharedState as k, DevframeDiagnosticsHost as kt, RpcFunctionsHost as l, DevframeServicesScopeRegistry as lt, RpcStreamingHost as m, DevframeSettings as mt, ConnectionMetaSse as n, DevframeServiceId as nt, DevframeNodeContext as o, DevframeServiceScopeOf as ot, RpcStreamingChannelOptions as p, DevframeScopedStreamingHost as pt, DevframeSnapshotRpcEntry as q, EventEmitter as qt, ConnectionMetaWebsocket as r, DevframeServiceInput as rt, DevframeNodeRpcSession as s, DevframeServicesHost as st, ConnectionMeta as t, DevframeServiceDescriptor as tt, RpcSharedStateGetOptions as u, DevframeServicesState as ut, StreamErrorPayload as v, ScopedClientFunctions as vt, Immutable as w, DevframeRpcClientFunctions as wt, StreamSinkEvents as x, ScopedSharedStates as xt, StreamReader as y, ScopedRpcFn as yt, McpServerHandle as z, AgentResourceContent as zt };
+export { DevframeServiceOf as $, EventUnsubscribe as $t, SharedStateEvents as A, McpFetchHandler as At, DevframeSetupInfo as B, parseCliFlags as Bt, createStreamSink as C, DevframeStorageScope as Ct, ImmutableObject as D, CreateMcpServerOptions as Dt, ImmutableMap as E, CreateMcpFetchHandlerOptions as Et, DevframeDefinition as F, McpServerHandle as Ft, McpAuthorization as G, AgentResourceInput as Gt, DevframeSnapshotRpcInputs as H, AgentManifest as Ht, DevframeDeploymentKind as I, DevframeAuthHandler as It, DevframeServiceDefinition as J, AgentToolProvider as Jt, McpRouteOptions as K, AgentTool as Kt, DevframeDockDefaults as L, CliFlagsSchema as Lt, SharedStatePatch as M, McpResourceTemplateContent as Mt, createSharedState as N, McpResourceTemplateEntry as Nt, ImmutableSet as O, McpConnectionInfo as Ot, DevframeCliOptions as P, McpResourcesChangedHook as Pt, DevframeServiceMeta as Q, EventEmitter as Qt, DevframeDuplicationStrategy as R, InferCliFlags as Rt, createStreamReader as S, DevframeHost as St, ImmutableArray as T, DevframeDiagnosticsLogger as Tt, DevframeSseOptions as U, AgentResource as Ut, DevframeSnapshotRpcEntry as V, AgentHandle as Vt, DevframeWsOptions as W, AgentResourceContent as Wt, DevframeServiceId as X, DevframeAgentHost as Xt, DevframeServiceDescriptor as Y, AgentToolProviderHandle as Yt, DevframeServiceInput as Z, DevframeAgentHostEvents as Zt, CreateStreamSinkOptions as _, DevframeViewHost as _t, DevframeConnectionConfigsRegistry as a, DevframeScopedNodeContext as at, StreamSink as b, DevframeRpcSharedStates as bt, RpcBroadcastOptions as c, DevframeSettings as ct, RpcSharedStateHost as d, ScopedBroadcastOptions as dt, EventsMap as en, DevframeServiceScopeOf as et, RpcStreamingChannel as f, ScopedClientFunctions as ft, CreateStreamReaderOptions as g, SettingsForNamespace as gt, BufferedChunk as h, ScopedSharedStates as ht, DevframeCapabilities as i, DevframeServicesState as it, SharedStateOptions as j, McpResourceTemplate as jt, SharedState as k, McpContentBlock as kt, RpcFunctionsHost as l, DevframeSettingsRegistry as lt, RpcStreamingHost as m, ScopedServerFunctions as mt, ConnectionMetaSse as n, DevframeServicesRegistry as nt, DevframeNodeContext as o, DevframeScopedNodeRpc as ot, RpcStreamingChannelOptions as p, ScopedRpcFn as pt, McpSetting as q, AgentToolInput as qt, ConnectionMetaWebsocket as r, DevframeServicesScopeRegistry as rt, DevframeNodeRpcSession as s, DevframeScopedStreamingHost as st, ConnectionMeta as t, DevframeServicesHost as tt, RpcSharedStateGetOptions as u, DevframeSettingsStore as ut, StreamErrorPayload as v, DevframeRpcClientFunctions as vt, Immutable as w, DevframeDiagnosticsHost as wt, StreamSinkEvents as x, BrowserAgentClientInfo as xt, StreamReader as y, DevframeRpcServerFunctions as yt, DevframeRpcOptions as z, defineCliFlags as zt };

package/dist/{context-O8NJzl93.d.mts → context-eIUOSrKu.d.mts}

@@ -1,4 +1,4 @@
-import { k as SharedState, o as DevframeNodeContext } from "./context-dOWXVHc6.mjs";
+import { k as SharedState, o as DevframeNodeContext } from "./context-Dko5QFWF.mjs";
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {
   trusted: Record<string, {

package/dist/{dev-pIWWAGYd.mjs → dev-C-wQTIrV.mjs}

@@ -1,10 +1,10 @@
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
-import { t as diagnostics } from "./diagnostics-Dngy7cNp.mjs";
-import { t as createHostContext } from "./context-CeD8-IZA.mjs";
-import { t as resolveStaticAssetsSource } from "./remote-assets-DoZ1AMpq.mjs";
-import { a as resolveMcpConfig, c as joinURL, d as withoutLeadingSlash, i as resolveDevServerPort, l as withBase, n as normalizeBasePath, r as resolveBasePath, s as importAgenticMcp, t as loadAutoMcpAdapter } from "./_shared-B6K2DKhb.mjs";
+import { t as diagnostics } from "./diagnostics-BJjvKfVK.mjs";
+import { t as createHostContext } from "./context-CmSDJAEI.mjs";
+import { t as resolveStaticAssetsSource } from "./remote-assets-DOva7l3s.mjs";
+import { a as resolveMcpConfig, c as joinURL, d as withoutLeadingSlash, i as resolveDevServerPort, l as withBase, n as normalizeBasePath, r as resolveBasePath, s as importAgenticMcp, t as loadAutoMcpAdapter } from "./_shared-C06DH07o.mjs";
 import { t as createH3DevframeHost } from "./host-h3-BROI6SQ4.mjs";
-import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-DyVmJA6B.mjs";
+import { a as isAddressInUse, i as normalizeHttpServerUrl, n as resolveInstanceRegister, o as listenWithLoopbackTwin, t as createInstanceShell } from "./instance-shell-CBgy8YzK.mjs";
 import { open } from "./utils/open.mjs";
 import { mountStaticHandler } from "./utils/serve-static.mjs";
 import { resolve } from "pathe";
@@ -141,6 +141,8 @@ async function mountMcpRoute(app, context, def, base, setting) {
 		serverVersion: def.version ?? "0.0.0",
 		exposeSharedState: config.exposeSharedState ?? true,
 		instructions: config.instructions,
+		resourceTemplates: config.resourceTemplates,
+		onResourcesChanged: config.onResourcesChanged,
 		authorization: config.authorization,
 		allowedOrigins: config.allowedOrigins
 	});
@@ -172,28 +174,11 @@ async function mountMcpRoute(app, context, def, base, setting) {
 async function createDevServer(def, options = {}) {
 	if (def.capabilities?.dev === false && !options.force) throw diagnostics.DF0058({ id: def.id });
 	const host = options.host ?? def.cli?.host ?? "localhost";
-	const requestedPort = options.port ?? await resolveDevServerPort(def, { host });
 	const flags = options.flags ?? {};
 	const basePath = options.basePath ? normalizeBasePath(options.basePath) : resolveBasePath(def, "standalone");
 	const app = options.app ?? new H3();
 	const server = createServer(toNodeHandler(app));
-	try {
-		await new Promise((resolveListen, rejectListen) => {
-			const onError = (error) => rejectListen(error);
-			server.once("error", onError);
-			server.listen(requestedPort, host, () => {
-				server.removeListener("error", onError);
-				resolveListen();
-			});
-		});
-	} catch (error) {
-		throw diagnostics.DF0052({
-			host,
-			port: requestedPort,
-			reason: error instanceof Error ? error.message : String(error),
-			cause: error
-		});
-	}
+	const { requestedPort, closeLoopbackTwin } = await listenDevServer(server, def, host, options);
 	const address = server.address();
 	const port = typeof address === "object" && address ? address.port : requestedPort;
 	const origin = normalizeHttpServerUrl(host, port);
@@ -231,6 +216,7 @@ async function createDevServer(def, options = {}) {
 	try {
 		await devframe.ready;
 	} catch (error) {
+		await closeLoopbackTwin();
 		await new Promise((resolveClose) => server.close(() => resolveClose()));
 		throw error;
 	}
@@ -251,10 +237,43 @@ async function createDevServer(def, options = {}) {
 		connectionMeta: transport.connectionMeta,
 		async close() {
 			await devframe.close();
+			await closeLoopbackTwin();
 			await new Promise((resolveClose) => server.close(() => resolveClose()));
 		}
 	};
 }
+/**
+* Bind the dev server. `getPort` probes only `host`, so it can call a port
+* free while another process holds it on the other loopback address of
+* `localhost`. The twin bind catches that, and a port that was not pinned
+* moves to the next free one.
+*/
+async function listenDevServer(server, def, host, options) {
+	let requestedPort = options.port ?? await resolveDevServerPort(def, {
+		host,
+		defaultPort: options.defaultPort
+	});
+	for (let attempt = 1;; attempt++) try {
+		return {
+			requestedPort,
+			closeLoopbackTwin: await listenWithLoopbackTwin(server, requestedPort, host)
+		};
+	} catch (error) {
+		if (options.port == null && attempt < 3 && isAddressInUse(error)) {
+			requestedPort = await resolveDevServerPort(def, {
+				host,
+				defaultPort: requestedPort + 1
+			});
+			continue;
+		}
+		throw diagnostics.DF0052({
+			host,
+			port: requestedPort,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+}
 async function maybeOpenBrowser(def, flags, origin, override, authHandler) {
 	const flagsOpen = flags.open;
 	const cliOpen = def.cli?.open;

package/dist/{diagnostics-Dngy7cNp.mjs → diagnostics-BJjvKfVK.mjs}

@@ -186,6 +186,14 @@ const diagnostics = defineDiagnostics({
 		DF0081: {
 			why: (p) => `Tool "${p.name}" returned invalid MCP content blocks: ${p.reason}`,
 			fix: "Pass `withMcpContent` a non-empty array of `{ type: 'text', text }`, `{ type: 'image', data, mimeType }` or `{ type: 'audio', data, mimeType }` blocks, with string fields and base64 `data`."
+		},
+		DF0082: {
+			why: (p) => `Tool "${p.tool}" was addressed to client "${p.clientId}", but no connected browser tab has that id and the tool.${p.live.length ? ` Connected clients: ${p.live.join(", ")}.` : " No browser tab is connected."}`,
+			fix: "Re-list the connected clients (`devframe:agent:list-clients`) and retry with a live `client_id`, or omit `client_id` to target the most recently focused tab."
+		},
+		DF0084: {
+			why: (p) => `MCP resource template "${p.name}" has an invalid \`uriTemplate\` "${p.uriTemplate}": ${p.reason}`,
+			fix: "Use RFC 6570 level 1 only: plain `{name}` expressions made of letters, digits, `_` and `.`, with no operator (`+`, `#`, `/`, `?`, …), modifier (`:n`, `*`) or list of names, and no `{` or `}` outside an expression."
 		}
 	}
 });

package/dist/in-page-channel/index.d.mts

@@ -1,5 +1,5 @@
 import { D as InferArgsType, E as Thenable, O as InferReturnType, T as RpcReturnSchema, m as RpcFunctionAgentOptions, n as RpcArgsSchema } from "../types-BmDbfHCx.mjs";
-import { k as SharedState, qt as EventEmitter } from "../context-dOWXVHc6.mjs";
+import { Qt as EventEmitter, k as SharedState } from "../context-Dko5QFWF.mjs";
 //#region src/in-page-channel/types.d.ts
 /**
  * The shared contract of one in-page channel, declared once (usually in a

package/dist/in-page-channel/index.mjs

@@ -1,6 +1,6 @@
 import { a as defineDiagnostics, i as createBirpc, n as argsToJsonSchema, o as DEVFRAME_EVENTS, r as resolveAgentSafety, t as toolInputToRpcArgs } from "../tool-input-CES3Pc4y.mjs";
 import { createEventEmitter } from "../utils/events.mjs";
-import { t as createSharedState } from "../shared-state-Cow3u-_m.mjs";
+import { t as createSharedState } from "../shared-state-Cc-Jrhma.mjs";
 import { nanoid } from "../utils/nanoid.mjs";
 import { r as registerBrowserAgentTool } from "../browser-agent-Pu-FLk6I.mjs";
 //#region src/in-page-channel/diagnostics.ts

package/dist/{index-DVGcpYm7.d.mts → index-BMj-o_sP.d.mts}

@@ -1,5 +1,5 @@
-import { k as SharedState, o as DevframeNodeContext, s as DevframeNodeRpcSession } from "./context-dOWXVHc6.mjs";
-import { n as InternalAnonymousAuthStorage } from "./context-O8NJzl93.mjs";
+import { k as SharedState, o as DevframeNodeContext, s as DevframeNodeRpcSession } from "./context-Dko5QFWF.mjs";
+import { n as InternalAnonymousAuthStorage } from "./context-eIUOSrKu.mjs";
 //#region src/node/auth/revoke.d.ts
 /**
  * Flip `isTrusted` to false on any live WS clients connected with `token`

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { C as RpcFunctionType, T as RpcReturnSchema, h as RpcFunctionDefinition, m as RpcFunctionAgentOptions, n as RpcArgsSchema } from "./types-BmDbfHCx.mjs";
-import { $ as McpSetting, At as DevframeDiagnosticsLogger, B as DevframeCliOptions, Bt as AgentResourceInput, Ct as DevframeViewHost, Dt as DevframeHost, Et as DevframeRpcSharedStates, F as CreateMcpServerOptions, G as DevframeRpcOptions, Gt as DevframeAgentHost, H as DevframeDeploymentKind, Ht as AgentToolInput, I as McpConnectionInfo, It as AgentHandle, J as DevframeSnapshotRpcInputs, Jt as EventUnsubscribe, K as DevframeSetupInfo, Kt as DevframeAgentHostEvents, L as McpContentBlock, Lt as AgentManifest, Ot as DevframeStorageScope, P as CreateMcpFetchHandlerOptions, Q as McpRouteOptions, R as McpFetchHandler, Rt as AgentResource, St as SettingsForNamespace, Tt as DevframeRpcServerFunctions, U as DevframeDockDefaults, Ut as AgentToolProvider, V as DevframeDefinition, Vt as AgentTool, W as DevframeDuplicationStrategy, Wt as AgentToolProviderHandle, X as DevframeWsOptions, Y as DevframeSseOptions, Yt as EventsMap, Z as McpAuthorization, _t as ScopedBroadcastOptions, a as DevframeConnectionConfigsRegistry, at as DevframeServiceOf, bt as ScopedServerFunctions, c as RpcBroadcastOptions, ct as DevframeServicesRegistry, d as RpcSharedStateHost, dt as DevframeScopedNodeContext, et as DevframeServiceDefinition, f as RpcStreamingChannel, ft as DevframeScopedNodeRpc, gt as DevframeSettingsStore, ht as DevframeSettingsRegistry, i as DevframeCapabilities, it as DevframeServiceMeta, kt as DevframeDiagnosticsHost, l as RpcFunctionsHost, lt as DevframeServicesScopeRegistry, m as RpcStreamingHost, mt as DevframeSettings, n as ConnectionMetaSse, nt as DevframeServiceId, o as DevframeNodeContext, ot as DevframeServiceScopeOf, p as RpcStreamingChannelOptions, pt as DevframeScopedStreamingHost, q as DevframeSnapshotRpcEntry, qt as EventEmitter, r as ConnectionMetaWebsocket, rt as DevframeServiceInput, s as DevframeNodeRpcSession, st as DevframeServicesHost, t as ConnectionMeta, tt as DevframeServiceDescriptor, u as RpcSharedStateGetOptions, ut as DevframeServicesState, vt as ScopedClientFunctions, wt as DevframeRpcClientFunctions, xt as ScopedSharedStates, yt as ScopedRpcFn, z as McpServerHandle, zt as AgentResourceContent } from "./context-dOWXVHc6.mjs";
+import { $ as DevframeServiceOf, $t as EventUnsubscribe, At as McpFetchHandler, B as DevframeSetupInfo, Ct as DevframeStorageScope, Dt as CreateMcpServerOptions, Et as CreateMcpFetchHandlerOptions, F as DevframeDefinition, Ft as McpServerHandle, G as McpAuthorization, Gt as AgentResourceInput, H as DevframeSnapshotRpcInputs, Ht as AgentManifest, I as DevframeDeploymentKind, J as DevframeServiceDefinition, Jt as AgentToolProvider, K as McpRouteOptions, Kt as AgentTool, L as DevframeDockDefaults, Mt as McpResourceTemplateContent, Nt as McpResourceTemplateEntry, Ot as McpConnectionInfo, P as DevframeCliOptions, Pt as McpResourcesChangedHook, Q as DevframeServiceMeta, Qt as EventEmitter, R as DevframeDuplicationStrategy, St as DevframeHost, Tt as DevframeDiagnosticsLogger, U as DevframeSseOptions, Ut as AgentResource, V as DevframeSnapshotRpcEntry, Vt as AgentHandle, W as DevframeWsOptions, Wt as AgentResourceContent, X as DevframeServiceId, Xt as DevframeAgentHost, Y as DevframeServiceDescriptor, Yt as AgentToolProviderHandle, Z as DevframeServiceInput, Zt as DevframeAgentHostEvents, _t as DevframeViewHost, a as DevframeConnectionConfigsRegistry, at as DevframeScopedNodeContext, bt as DevframeRpcSharedStates, c as RpcBroadcastOptions, ct as DevframeSettings, d as RpcSharedStateHost, dt as ScopedBroadcastOptions, en as EventsMap, et as DevframeServiceScopeOf, f as RpcStreamingChannel, ft as ScopedClientFunctions, gt as SettingsForNamespace, ht as ScopedSharedStates, i as DevframeCapabilities, it as DevframeServicesState, jt as McpResourceTemplate, kt as McpContentBlock, l as RpcFunctionsHost, lt as DevframeSettingsRegistry, m as RpcStreamingHost, mt as ScopedServerFunctions, n as ConnectionMetaSse, nt as DevframeServicesRegistry, o as DevframeNodeContext, ot as DevframeScopedNodeRpc, p as RpcStreamingChannelOptions, pt as ScopedRpcFn, q as McpSetting, qt as AgentToolInput, r as ConnectionMetaWebsocket, rt as DevframeServicesScopeRegistry, s as DevframeNodeRpcSession, st as DevframeScopedStreamingHost, t as ConnectionMeta, tt as DevframeServicesHost, u as RpcSharedStateGetOptions, ut as DevframeSettingsStore, vt as DevframeRpcClientFunctions, wt as DevframeDiagnosticsHost, yt as DevframeRpcServerFunctions, z as DevframeRpcOptions } from "./context-Dko5QFWF.mjs";
 import { a as DevframeWsPeer, i as DevframeRpcTransportKind, n as DevframeRpcConnection, r as DevframeRpcConnectionRequest, t as DevframeNodeRpcSessionMeta } from "./session-r6PDixP6.mjs";
 import { a as RemoteAssetsStore, i as RemoteAssetsProviderCustom, n as RemoteAssetsErrorMessage, o as StaticAssetsSource, r as RemoteAssetsProvider, t as RemoteAssets } from "./remote-assets-eBvSKZMS.mjs";
 import { i as DevframeDefineDiagnosticsOptions } from "./nostics-DWvukRwa.mjs";
-import { n as withMcpContent } from "./mcp-content-9_Pdtziq.mjs";
+import { n as withMcpContent } from "./mcp-content-wcQxvrrW.mjs";
 //#region src/define.d.ts
 export 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>;
 /**
@@ -12,4 +12,4 @@ export declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFu
  */
 export declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaSse, type ConnectionMetaWebsocket, type CreateMcpFetchHandlerOptions, type CreateMcpServerOptions, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeCapabilities, type DevframeCliOptions, type DevframeConnectionConfigsRegistry, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, type DevframeRpcOptions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRpcTransportKind, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceDefinition, type DevframeServiceDescriptor, type DevframeServiceId, type DevframeServiceInput, type DevframeServiceMeta, type DevframeServiceOf, type DevframeServiceScopeOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeServicesScopeRegistry, type DevframeServicesState, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSnapshotRpcEntry, type DevframeSnapshotRpcInputs, type DevframeSseOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type DevframeWsPeer, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpAuthorization, type McpConnectionInfo, type McpContentBlock, type McpFetchHandler, type McpRouteOptions, type McpServerHandle, type McpSetting, type RemoteAssets, type RemoteAssetsErrorMessage, type RemoteAssetsProvider, type RemoteAssetsProviderCustom, type RemoteAssetsStore, 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 StaticAssetsSource, withMcpContent };
+export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaSse, type ConnectionMetaWebsocket, type CreateMcpFetchHandlerOptions, type CreateMcpServerOptions, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeCapabilities, type DevframeCliOptions, type DevframeConnectionConfigsRegistry, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, type DevframeRpcOptions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRpcTransportKind, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceDefinition, type DevframeServiceDescriptor, type DevframeServiceId, type DevframeServiceInput, type DevframeServiceMeta, type DevframeServiceOf, type DevframeServiceScopeOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeServicesScopeRegistry, type DevframeServicesState, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSnapshotRpcEntry, type DevframeSnapshotRpcInputs, type DevframeSseOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type DevframeWsPeer, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpAuthorization, type McpConnectionInfo, type McpContentBlock, type McpFetchHandler, type McpResourceTemplate, type McpResourceTemplateContent, type McpResourceTemplateEntry, type McpResourcesChangedHook, type McpRouteOptions, type McpServerHandle, type McpSetting, type RemoteAssets, type RemoteAssetsErrorMessage, type RemoteAssetsProvider, type RemoteAssetsProviderCustom, type RemoteAssetsStore, 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 StaticAssetsSource, withMcpContent };

package/dist/{instance-registry-B--XFmLS.mjs → instance-registry-vlz81P9X.mjs}

@@ -1,5 +1,5 @@
 import { n as __exportAll } from "./rolldown-runtime-B4iAMlE-.mjs";
-import { t as diagnostics } from "./diagnostics-Dngy7cNp.mjs";
+import { t as diagnostics } from "./diagnostics-BJjvKfVK.mjs";
 import { join } from "pathe";
 import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import process from "node:process";