devframe 1.2.5 → 1.3.0

package/dist/{context-DhycZ2lx.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.
  */
@@ -1289,6 +1477,30 @@ interface McpRouteOptions {
    * The states themselves stay available to the UI over RPC.
    */
   exposeSharedState?: boolean | ((key: string) => boolean);
+  /**
+   * Usage guidance for the route, sent as `instructions` in the MCP
+   * `initialize` (and `server/discover`) result. An MCP client can add it to
+   * the coding agent's context, for example to say which tool to call first.
+   * 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`. */
@@ -1590,95 +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);
-  /** 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;
-}
-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);
-  /**
-   * 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>;
@@ -2280,4 +2403,4 @@ interface ConnectionMeta {
  */
 interface DevframeConnectionConfigsRegistry {}
 //#endregion
-export { DevframeServiceDefinition as $, SharedStateEvents as A, DevframeAuthHandler as At, DevframeDefinition as B, AgentTool as Bt, createStreamSink as C, DevframeRpcClientFunctions as Ct, ImmutableObject as D, DevframeStorageScope as Dt, ImmutableMap as E, DevframeHost as Et, CreateMcpServerOptions as F, AgentHandle as Ft, DevframeSetupInfo as G, DevframeAgentHostEvents as Gt, DevframeDockDefaults as H, AgentToolProvider as Ht, McpConnectionInfo as I, AgentManifest as It, DevframeSseOptions as J, EventsMap as Jt, DevframeSnapshotRpcEntry as K, EventEmitter as Kt, McpFetchHandler as L, AgentResource as Lt, SharedStatePatch as M, InferCliFlags as Mt, createSharedState as N, defineCliFlags as Nt, ImmutableSet as O, DevframeDiagnosticsHost as Ot, CreateMcpFetchHandlerOptions as P, parseCliFlags as Pt, McpSetting as Q, McpServerHandle as R, AgentResourceContent as Rt, createStreamReader as S, DevframeViewHost as St, ImmutableArray as T, DevframeRpcSharedStates as Tt, DevframeDuplicationStrategy as U, AgentToolProviderHandle as Ut, DevframeDeploymentKind as V, AgentToolInput as Vt, DevframeRpcOptions as W, DevframeAgentHost as Wt, McpAuthorization as X, DevframeWsOptions as Y, McpRouteOptions as Z, CreateStreamSinkOptions as _, ScopedClientFunctions as _t, DevframeConnectionConfigsRegistry as a, DevframeServiceScopeOf as at, StreamSink as b, ScopedSharedStates as bt, RpcBroadcastOptions as c, DevframeServicesScopeRegistry as ct, RpcSharedStateHost as d, DevframeScopedNodeRpc as dt, DevframeServiceDescriptor as et, RpcStreamingChannel as f, DevframeScopedStreamingHost as ft, CreateStreamReaderOptions as g, ScopedBroadcastOptions as gt, BufferedChunk as h, DevframeSettingsStore as ht, DevframeCapabilities as i, DevframeServiceOf as it, SharedStateOptions as j, CliFlagsSchema as jt, SharedState as k, DevframeDiagnosticsLogger as kt, RpcFunctionsHost as l, DevframeServicesState as lt, RpcStreamingHost as m, DevframeSettingsRegistry as mt, ConnectionMetaSse as n, DevframeServiceInput as nt, DevframeNodeContext as o, DevframeServicesHost as ot, RpcStreamingChannelOptions as p, DevframeSettings as pt, DevframeSnapshotRpcInputs as q, EventUnsubscribe as qt, ConnectionMetaWebsocket as r, DevframeServiceMeta as rt, DevframeNodeRpcSession as s, DevframeServicesRegistry as st, ConnectionMeta as t, DevframeServiceId as tt, RpcSharedStateGetOptions as u, DevframeScopedNodeContext as ut, StreamErrorPayload as v, ScopedRpcFn as vt, Immutable as w, DevframeRpcServerFunctions as wt, StreamSinkEvents as x, SettingsForNamespace as xt, StreamReader as y, ScopedServerFunctions as yt, DevframeCliOptions as z, AgentResourceInput 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-Bgvuxv1C.d.mts → context-eIUOSrKu.d.mts}

@@ -1,4 +1,4 @@
-import { k as SharedState, o as DevframeNodeContext } from "./context-DhycZ2lx.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-BViAfnlw.mjs → dev-C-wQTIrV.mjs}

@@ -1,10 +1,10 @@
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
-import { t as diagnostics } from "./diagnostics-Cx4_VjlG.mjs";
-import { t as createHostContext } from "./context-BKw9KkCR.mjs";
-import { t as resolveStaticAssetsSource } from "./remote-assets-B9MeWmW6.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-DlRoV7v3.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-DmyVIJzj.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";
@@ -140,6 +140,9 @@ async function mountMcpRoute(app, context, def, base, setting) {
 		serverName: `${def.id} (devframe)`,
 		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
 	});
@@ -171,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);
@@ -230,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;
 	}
@@ -250,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-Cx4_VjlG.mjs → diagnostics-BJjvKfVK.mjs}

@@ -182,6 +182,18 @@ const diagnostics = defineDiagnostics({
 		DF0079: {
 			why: (p) => `The \`mcp\` option is enabled, but the optional peer "@devframes/agentic" could not be loaded: ${p.reason}`,
 			fix: "Install `@devframes/agentic` next to devframe (the MCP adapter and the MCP SDK live there), or remove the explicit `mcp` setting."
+		},
+		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 { Kt as EventEmitter, k as SharedState } from "../context-DhycZ2lx.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-DFPsvDGu.d.mts → index-BMj-o_sP.d.mts}

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

@@ -1,3 +1,4 @@
+import { n as withMcpContent } from "./mcp-content-DN3O212x.mjs";
 import { t as createDefineWrapperWithContext } from "./define-BLWPsH6y.mjs";
 //#region src/define.ts
 const defineRpcFunction = createDefineWrapperWithContext();
@@ -9,4 +10,4 @@ function defineDevframe(d) {
 	return d;
 }
 //#endregion
-export { defineDevframe, defineRpcFunction };
+export { defineDevframe, defineRpcFunction, withMcpContent };

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

@@ -1,5 +1,5 @@
 import { n as __exportAll } from "./rolldown-runtime-B4iAMlE-.mjs";
-import { t as diagnostics } from "./diagnostics-Cx4_VjlG.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";