devframe 0.7.16 → 0.8.0

package/dist/client/index.mjs

@@ -68,6 +68,14 @@ const diagnostics = defineDiagnostics({
 		DF0028: {
 			why: (p) => `Function "${p.name}" with type "${p.type}" cannot use \`snapshot: true\`. Only "query" functions support this sugar; "static" functions have equivalent default behavior already.`,
 			fix: "Remove `snapshot: true`, or change the function type to `query`."
+		},
+		DF0043: {
+			why: (p) => `RPC function "${p.name}" received an invalid argument at position ${p.index}: ${p.issues}`,
+			fix: "Pass a value that satisfies the `args` schema declared for this function."
+		},
+		DF0044: {
+			why: (p) => `RPC function "${p.name}" returned a value that failed its \`returns\` schema: ${p.issues}`,
+			fix: "Make the handler return a value that satisfies the `returns` schema, or relax the schema."
 		}
 	}
 });
@@ -92,6 +100,70 @@ function isPlainErrorShape(value) {
 	return typeof value === "object" && value !== null && typeof value.message === "string" && typeof value.name === "string";
 }
 //#endregion
+//#region src/rpc/validate-io.ts
+/**
+* Run a single [Standard Schema](https://standardschema.dev) validator,
+* awaiting the result when the validator is asynchronous.
+*/
+async function runStandardSchema(schema, value) {
+	const result = schema["~standard"].validate(value);
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Render Standard Schema issues into a single human-readable line for a
+* diagnostic message, prefixing each with its dotted path when present.
+*/
+function formatIssues(issues) {
+	return issues.map((issue) => {
+		const path = issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+/**
+* 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
+*/
+async function validateRpcArgs(name, argsSchema, args) {
+	const original = args.slice();
+	if (!argsSchema || argsSchema.length === 0) return original;
+	for (let index = 0; index < argsSchema.length; index++) {
+		const schema = argsSchema[index];
+		if (!schema) continue;
+		const result = await runStandardSchema(schema, args[index]);
+		if (result.issues) throw diagnostics.DF0043({
+			name,
+			index,
+			issues: formatIssues(result.issues)
+		});
+	}
+	return original;
+}
+/**
+* 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
+*/
+async function validateRpcReturn(name, returnSchema, value) {
+	if (!returnSchema) return value;
+	const result = await runStandardSchema(returnSchema, value);
+	if (result.issues) throw diagnostics.DF0044({
+		name,
+		issues: formatIssues(result.issues)
+	});
+	return value;
+}
+//#endregion
 //#region src/rpc/handler.ts
 async function getRpcResolvedSetupResult(definition, context) {
 	if (!definition.setup) return {};
@@ -118,10 +190,22 @@ async function getRpcResolvedSetupResult(definition, context) {
 	return await definition.__promise;
 }
 async function getRpcHandler(definition, context) {
-	if (definition.handler) return definition.handler;
-	const result = await getRpcResolvedSetupResult(definition, context);
-	if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
-	return result.handler;
+	let handler = definition.handler;
+	if (!handler) {
+		const result = await getRpcResolvedSetupResult(definition, context);
+		if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
+		handler = result.handler;
+	}
+	const argsSchema = definition.args;
+	const returnSchema = definition.returns;
+	if (!argsSchema && !returnSchema) return handler;
+	const inner = handler;
+	const validating = async (...args) => {
+		const validatedArgs = await validateRpcArgs(definition.name, argsSchema, args);
+		const output = await inner(...validatedArgs);
+		return await validateRpcReturn(definition.name, returnSchema, output);
+	};
+	return validating;
 }
 //#endregion
 //#region src/rpc/cache.ts

package/dist/{context-CzqPrJSz.d.mts → context-7BbaIUSI.d.mts}

@@ -1,4 +1,4 @@
-import { b as DevframeNodeContext, ht as SharedState } from "./devframe-Ckhf3kFw.mjs";
+import { b as DevframeNodeContext, ht as SharedState } from "./devframe-Dsjn_Xtq.mjs";
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {
   trusted: Record<string, {

package/dist/{context-DY72brRI.mjs → context-C9Cgm1hP.mjs}

@@ -1,4 +1,4 @@
-import { t as createStorage } from "./storage-gEnj9ASQ.mjs";
+import { t as createStorage } from "./storage-Dzoc3NVC.mjs";
 import { i as randomToken, n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-BtQDKTp7.mjs";
 import { join } from "pathe";
 //#region src/node/hub-internals/context.ts

package/dist/{dev-BCeaQuGE.mjs → dev-D4M7Veo7.mjs}

@@ -1,7 +1,8 @@
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
-import { a as diagnostics } from "./storage-gEnj9ASQ.mjs";
-import { n as createHostContext, t as createH3DevframeHost } from "./host-h3-CgOetlNE.mjs";
-import { i as normalizeHttpServerUrl, t as startHttpAndWs } from "./server-DykHCza_.mjs";
+import { n as createHostContext, t as createH3DevframeHost } from "./host-h3-Kz7t5Xab.mjs";
+import { t as diagnostics } from "./diagnostics-B5-qHeqD.mjs";
+import { r as registerDevframeInstance } from "./instance-registry-D6fxYu36.mjs";
+import { i as normalizeHttpServerUrl, t as startHttpAndWs } from "./server-CcAPxuoT.mjs";
 import { n as resolveBasePath, t as normalizeBasePath } from "./_shared-bWRzeSa0.mjs";
 import { t as open } from "./open-Deb5xmIT.mjs";
 import { mountStaticHandler } from "./utils/serve-static.mjs";
@@ -294,7 +295,7 @@ async function createDevServer(def, options = {}) {
 		const mcpPath = joinURL(basePath, mcpRoute);
 		let mountMcpHttp;
 		try {
-			({mountMcpHttp} = await import("./http-_pPbryTQ.mjs"));
+			({mountMcpHttp} = await import("./http-BghOqfTD.mjs"));
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			throw diagnostics.DF0017({
@@ -344,13 +345,23 @@ async function createDevServer(def, options = {}) {
 			await maybeOpenBrowser(def, flags, `${info.origin}${basePath}`, options.openBrowser, authHandler);
 		}
 	});
-	if (mcpDispose) {
-		const closeServer = started.close;
-		started.close = async () => {
-			await mcpDispose();
-			await closeServer();
-		};
-	}
+	const registration = registerDevframeInstance({
+		pid: process$1.pid,
+		port: started.port,
+		origin: normalizeHttpServerUrl(host, started.port),
+		basePath,
+		id: def.id,
+		name: def.name,
+		rootDir: process$1.cwd(),
+		mcp: mcpConfig ? { path: joinURL(basePath, withoutLeadingSlash(mcpConfig.path ?? "__mcp")) } : null,
+		startedAt: Date.now()
+	});
+	const closeServer = started.close;
+	started.close = async () => {
+		registration.unregister();
+		await mcpDispose?.();
+		await closeServer();
+	};
 	return started;
 }
 /**

package/dist/{devframe-Ckhf3kFw.d.mts → devframe-Dsjn_Xtq.d.mts}

@@ -1,8 +1,8 @@
-import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-CrzNxXKq.mjs";
-import { S as RpcFunctionsCollectorBase } from "./index-DgsLFhZg.mjs";
-import { t as DevframeNodeRpcSessionMeta } from "./ws-server-9-wn7MNQ.mjs";
+import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-CnJSgRVa.mjs";
+import { w as RpcFunctionsCollectorBase } from "./index-Dbw1p5ch.mjs";
+import { t as DevframeNodeRpcSessionMeta } from "./ws-server-D_Vjtums.mjs";
 import { CAC } from "cac";
-import { GenericSchema, InferOutput } from "valibot";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 import { Peer } from "crossws";
 import { BirpcReturn } from "birpc";
 import { Diagnostic, DiagnosticDefinition, defineDiagnostics } from "nostics";
@@ -10,11 +10,12 @@ import { Diagnostic, DiagnosticDefinition, defineDiagnostics } from "nostics";
 /**
  * Schema map for typed CLI flags. Keys are flag names in camelCase —
  * this matches CAC's parsed-flag output ( `--no-open` → `noOpen` ). Each
- * value is a valibot schema used to both (a) derive the CAC option type
- * when the flag is registered and (b) validate / coerce the parsed
- * value before it's forwarded to `setup(ctx, { flags })`.
+ * value is any [Standard Schema](https://standardschema.dev/) validator
+ * (valibot, zod, arktype, devframe's built-in `s`, …) used to both (a)
+ * derive the CAC option type when the flag is registered and (b) validate
+ * the parsed value before it's forwarded to `setup(ctx, { flags })`.
  */
-type CliFlagsSchema = Record<string, GenericSchema>;
+type CliFlagsSchema = Record<string, StandardSchemaV1>;
 /**
  * Identity helper that preserves the literal schema-map type — use this
  * so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
@@ -37,8 +38,8 @@ type CliFlagsSchema = Record<string, GenericSchema>;
  */
 declare function defineCliFlags<T extends CliFlagsSchema>(flags: T): T;
 /** Extract the parsed-output type from a {@link CliFlagsSchema}. */
-type InferCliFlags<T extends CliFlagsSchema> = { [K in keyof T]: InferOutput<T[K]>; };
-/** Validate and coerce the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+type InferCliFlags<T extends CliFlagsSchema> = { [K in keyof T]: StandardSchemaV1.InferOutput<T[K]>; };
+/** Validate the raw cac-parsed bag against a {@link CliFlagsSchema}. */
 declare function parseCliFlags(schema: CliFlagsSchema, raw: Record<string, unknown>): {
   flags: Record<string, unknown>;
   issues?: string[];
@@ -138,6 +139,14 @@ interface AgentTool {
   tags?: readonly string[];
   /** Present for `kind === 'rpc'` — points to the RPC function name. */
   rpcName?: string;
+  /**
+   * Positional Standard Schemas describing a `kind: 'tool'` entry's
+   * arguments — carried on the tool itself (mirroring how `rpcName` defers
+   * an RPC-backed tool's schemas to `ctx.rpc.definitions`) so consumers
+   * (e.g. the MCP adapter) convert Standard Schema → JSON Schema on demand,
+   * same as RPC `args`.
+   */
+  args?: readonly StandardSchemaV1[];
   /** JSON Schema describing the input (positional args synthesized to an object). */
   inputSchema?: unknown;
   /** JSON Schema describing the output. */
@@ -160,6 +169,17 @@ interface AgentToolInput {
   description: string;
   safety?: 'read' | 'action' | 'destructive';
   tags?: readonly string[];
+  /**
+   * Positional Standard Schemas describing the tool's arguments — the same
+   * shape RPC definitions carry (any [Standard Schema](https://standardschema.dev/)
+   * validator: valibot, zod, arktype, devframe's built-in `s` builder, …).
+   * Each is advertised under `arg0` / `arg1` / … on the tool's JSON-Schema
+   * input, matching how the agent bridge coerces the incoming payload back
+   * into positional arguments. Purely descriptive: the handler still
+   * receives the caller's args object as-is.
+   */
+  args?: readonly StandardSchemaV1[];
+  /** Raw JSON-Schema input override. Prefer {@link args}. */
   inputSchema?: unknown;
   outputSchema?: unknown;
   examples?: readonly {
@@ -227,6 +247,33 @@ interface AgentManifest {
 interface AgentHandle {
   unregister: () => void;
 }
+/**
+ * A lazy source of agent tools, queried at `list()` / `getTool()` /
+ * `invoke()` time — the same on-demand projection the host applies to
+ * `agent`-flagged RPC definitions. Use a provider when tools *derive from*
+ * other state (a command registry, a plugin catalog): the underlying state
+ * stays the single source of truth and nothing needs to be kept in sync.
+ *
+ * Providers should namespace tool ids like any other tool; on an id
+ * collision the earlier source wins (registered tools, then RPC tools,
+ * then providers in registration order).
+ *
+ * @experimental
+ */
+type AgentToolProvider = () => readonly AgentToolInput[];
+/**
+ * Handle returned by `registerToolProvider`.
+ *
+ * @experimental
+ */
+interface AgentToolProviderHandle extends AgentHandle {
+  /**
+   * Signal that the provider's tool set changed. Fires
+   * `agent:manifest:changed` so protocol adapters (e.g. MCP) emit
+   * `tools/list_changed`.
+   */
+  notifyChanged: () => void;
+}
 /**
  * Events emitted by `DevframeAgentHost`.
  *
@@ -262,6 +309,11 @@ interface DevframeAgentHost {
   registerTool: (tool: AgentToolInput) => AgentHandle;
   /** Unregister a previously registered tool by id. */
   unregisterTool: (id: string) => boolean;
+  /**
+   * Register a lazy tool source, queried on demand — see
+   * {@link AgentToolProvider}.
+   */
+  registerToolProvider: (provider: AgentToolProvider) => AgentToolProviderHandle;
   /** Register a readable resource. */
   registerResource: (resource: AgentResourceInput) => AgentHandle;
   /** Unregister a previously registered resource by id. */
@@ -1579,10 +1631,11 @@ interface DevframeCliOptions {
    */
   configure?: (cli: CAC) => void;
   /**
-   * Typed CLI flags for the default `dev` command, backed by valibot
-   * schemas. The adapter registers matching `--kebab-key` options on
-   * CAC, validates the parsed values, and forwards the typed bag to
-   * `setup(ctx, { flags })`.
+   * Typed CLI flags for the default `dev` command, backed by any
+   * [Standard Schema](https://standardschema.dev/) validator (valibot,
+   * zod, arktype, or devframe's built-in `s`). The adapter registers
+   * matching `--kebab-key` options on CAC, validates the parsed values,
+   * and forwards the typed bag to `setup(ctx, { flags })`.
    *
    * Use {@link defineCliFlags} to preserve the literal schema-map
    * shape, and {@link InferCliFlags} to recover the typed output at the
@@ -1737,4 +1790,4 @@ interface DevframeDefinition {
 }
 declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { DevframeRpcServerFunctions as $, DevframeSettingsStore as A, EventUnsubscribe as At, DevframeDefineDiagnosticsOptions as B, DevframeServicesHost as C, AgentResourceContent as Ct, DevframeScopedStreamingHost as D, DevframeAgentHost as Dt, DevframeScopedNodeRpc as E, AgentToolInput as Et, ScopedSharedStates as F, parseCliFlags as Ft, RpcBroadcastOptions as G, DevframeDiagnosticsHost as H, SettingsForNamespace as I, RpcSharedStateHost as J, RpcFunctionsHost as K, DevframeViewHost as L, ScopedClientFunctions as M, CliFlagsSchema as Mt, ScopedRpcFn as N, InferCliFlags as Nt, DevframeSettings as O, DevframeAgentHostEvents as Ot, ScopedServerFunctions as P, defineCliFlags as Pt, DevframeRpcClientFunctions as Q, DevframeHost as R, DevframeServiceOf as S, AgentResource as St, DevframeScopedNodeContext as T, AgentTool as Tt, DevframeDiagnosticsLogger as U, DevframeDiagnosticsDefinition as V, DevframeNodeRpcSession as W, RpcStreamingChannelOptions as X, RpcStreamingChannel as Y, RpcStreamingHost as Z, ConnectionMeta as _, SharedStateOptions as _t, DevframeDockDefaults as a, StreamReader as at, DevframeNodeContext as b, AgentHandle as bt, DevframeSetupInfo as c, createStreamReader as ct, McpRouteOptions as d, ImmutableArray as dt, DevframeRpcSharedStates as et, defineDevframe as f, ImmutableMap as ft, Thenable as g, SharedStateEvents as gt, PartialWithoutId as h, SharedState as ht, DevframeDeploymentKind as i, StreamErrorPayload as it, ScopedBroadcastOptions as j, EventsMap as jt, DevframeSettingsRegistry as k, EventEmitter as kt, DevframeSpaOptions as l, createStreamSink as lt, EntriesToObject as m, ImmutableSet as mt, DevframeCliOptions as n, CreateStreamReaderOptions as nt, DevframeDuplicationStrategy as o, StreamSink as ot, DevframeAuthHandler as p, ImmutableObject as pt, RpcSharedStateGetOptions as q, DevframeDefinition as r, CreateStreamSinkOptions as rt, DevframeRuntime as s, StreamSinkEvents as st, DevframeBrowserContext as t, BufferedChunk as tt, DevframeWsOptions as u, Immutable as ut, ConnectionMetaWebsocket as v, SharedStatePatch as vt, DevframeServicesRegistry as w, AgentResourceInput as wt, DevframeServiceId as x, AgentManifest as xt, DevframeCapabilities as y, createSharedState as yt, DevframeStorageScope as z };
+export { DevframeRpcServerFunctions as $, DevframeSettingsStore as A, DevframeAgentHostEvents as At, DevframeDefineDiagnosticsOptions as B, DevframeServicesHost as C, AgentResourceContent as Ct, DevframeScopedStreamingHost as D, AgentToolProvider as Dt, DevframeScopedNodeRpc as E, AgentToolInput as Et, ScopedSharedStates as F, InferCliFlags as Ft, RpcBroadcastOptions as G, DevframeDiagnosticsHost as H, SettingsForNamespace as I, defineCliFlags as It, RpcSharedStateHost as J, RpcFunctionsHost as K, DevframeViewHost as L, parseCliFlags as Lt, ScopedClientFunctions as M, EventUnsubscribe as Mt, ScopedRpcFn as N, EventsMap as Nt, DevframeSettings as O, AgentToolProviderHandle as Ot, ScopedServerFunctions as P, CliFlagsSchema as Pt, DevframeRpcClientFunctions as Q, DevframeHost as R, DevframeServiceOf as S, AgentResource as St, DevframeScopedNodeContext as T, AgentTool as Tt, DevframeDiagnosticsLogger as U, DevframeDiagnosticsDefinition as V, DevframeNodeRpcSession as W, RpcStreamingChannelOptions as X, RpcStreamingChannel as Y, RpcStreamingHost as Z, ConnectionMeta as _, SharedStateOptions as _t, DevframeDockDefaults as a, StreamReader as at, DevframeNodeContext as b, AgentHandle as bt, DevframeSetupInfo as c, createStreamReader as ct, McpRouteOptions as d, ImmutableArray as dt, DevframeRpcSharedStates as et, defineDevframe as f, ImmutableMap as ft, Thenable as g, SharedStateEvents as gt, PartialWithoutId as h, SharedState as ht, DevframeDeploymentKind as i, StreamErrorPayload as it, ScopedBroadcastOptions as j, EventEmitter as jt, DevframeSettingsRegistry as k, DevframeAgentHost as kt, DevframeSpaOptions as l, createStreamSink as lt, EntriesToObject as m, ImmutableSet as mt, DevframeCliOptions as n, CreateStreamReaderOptions as nt, DevframeDuplicationStrategy as o, StreamSink as ot, DevframeAuthHandler as p, ImmutableObject as pt, RpcSharedStateGetOptions as q, DevframeDefinition as r, CreateStreamSinkOptions as rt, DevframeRuntime as s, StreamSinkEvents as st, DevframeBrowserContext as t, BufferedChunk as tt, DevframeWsOptions as u, Immutable as ut, ConnectionMetaWebsocket as v, SharedStatePatch as vt, DevframeServicesRegistry as w, AgentResourceInput as wt, DevframeServiceId as x, AgentManifest as xt, DevframeCapabilities as y, createSharedState as yt, DevframeStorageScope as z };

package/dist/diagnostics-B5-qHeqD.mjs

@@ -0,0 +1,94 @@
+import { t as devframeReporter } from "./diagnostics-reporter-CsIG85Q5.mjs";
+import { defineDiagnostics } from "nostics";
+//#region src/node/diagnostics.ts
+const diagnostics = defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	reporters: [devframeReporter],
+	codes: {
+		DF0006: { why: (p) => `RPC function "${p.name}" is not registered` },
+		DF0007: { why: "AsyncLocalStorage is not set, it likely to be an internal bug of the Devframe foundation" },
+		DF0008: { why: (p) => `distDir ${p.distDir} does not exist` },
+		DF0012: { why: (p) => `Failed to parse storage file: ${p.filepath}, falling back to defaults.` },
+		DF0013: { why: (p) => `Shared state of "${p.key}" is not found, please provide an initial value for the first time` },
+		DF0014: {
+			why: (p) => `RPC function "${p.name}" has an invalid \`agent\` field — \`description\` must be a non-empty string.`,
+			fix: "Provide a short description (~1–3 sentences) explaining what the tool does and when agents should invoke it."
+		},
+		DF0015: {
+			why: (p) => `Agent tool "${p.id}" is already registered.`,
+			fix: "Tool ids must be unique across RPC functions with an `agent` field and tools registered via `ctx.agent.registerTool()`."
+		},
+		DF0016: { why: (p) => `Agent resource "${p.id}" is already registered.` },
+		DF0017: { why: (p) => `Failed to start MCP server (${p.transport}): ${p.reason}` },
+		DF0029: {
+			why: (p) => `Stream "${p.channel}#${p.id}" dropped ${p.dropped} chunk(s) after exceeding the client high-water mark.`,
+			fix: "The consumer is too slow for the producer. Raise `highWaterMark` on the subscription, slow the producer, or batch chunks."
+		},
+		DF0030: {
+			why: (p) => `Stream "${p.channel}#${p.id}" is unknown — no producer has called \`channel.start({ id: "${p.id}" })\`.`,
+			fix: "Ensure the server-side producer is running before clients subscribe, or check for typos in the stream id."
+		},
+		DF0031: {
+			why: (p) => `Cannot write to closed stream "${p.channel}#${p.id}".`,
+			fix: "Track the producer lifecycle — guard writes with the `stream.signal.aborted` flag."
+		},
+		DF0032: {
+			why: (p) => `Streaming channel "${p.channel}" is already registered.`,
+			fix: "Each channel name must be unique within a context. Pick a different name or reuse the existing channel handle."
+		},
+		DF0033: {
+			why: (p) => `Failed to start dev RPC bridge for "${p.id}": ${p.reason}`,
+			fix: "Verify the bridge port is free and the devframe setup function does not throw. Pin a port via `cli.port` / `cli.portRange` on the definition, or via `devMiddleware.port` on `viteDevBridge`."
+		},
+		DF0034: {
+			why: (p) => `Scoped RPC registration for namespace "${p.namespace}" received an already-namespaced function name "${p.name}".`,
+			fix: "A scoped context auto-namespaces ids. Pass a bare name without a \":\" separator (e.g. `register({ name: \"get-cwd\" })`), or use the unscoped `ctx.base.rpc.register` for a fully-qualified name."
+		},
+		DF0035: {
+			why: (p) => `Failed to persist storage file: ${p.filepath}`,
+			fix: "Check that the storage directory is writable and has free space."
+		},
+		DF0036: {
+			why: (p) => `RPC call to "${p.name}" was rejected: the caller is not authorized.`,
+			fix: "Complete the auth handshake (or connect with a static/pre-shared token) before calling a trusted method. Untrusted callers may only call `anonymous:`-prefixed methods — see `isAnonymousRpcMethod`."
+		},
+		DF0037: {
+			why: (p) => `A service is already provided under "${p.id}".`,
+			fix: "Service ids are unique per context. Revoke the existing provider first (the `provide()` call returns a revoke function), or namespace the id with your plugin id to avoid collisions."
+		},
+		DF0042: {
+			why: (p) => `"${p.id}" declares \`capabilities.build: false\` — its static export is not meaningful (writes are excluded and any live-served data won't be there).`,
+			fix: "Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you, or drop `capabilities.build: false` on the definition."
+		},
+		DF0045: {
+			why: (p) => `Failed to update the devframe instance registry at "${p.file}": ${p.reason}`,
+			fix: "Discovery tooling (`devframe connect`) will not see this instance. Check that the registry directory is writable, point `DEVFRAME_INSTANCES_DIR` at a writable directory, or set `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` to opt out of registration."
+		},
+		DF0046: {
+			why: (p) => `\`devframe connect\` requires the optional peer dependency @modelcontextprotocol/server: ${p.reason}`,
+			fix: "Install it next to devframe (e.g. `npm install @modelcontextprotocol/server`) and run `devframe connect` again."
+		},
+		DF0047: {
+			why: (p) => `Agent tool "${p.id}" is hidden from the MCP surface: its wire name "${p.name}" collides with the tool "${p.existing}".`,
+			fix: "Wire names derive from tool ids (characters outside [a-zA-Z0-9_-] become \"_\"). Rename one of the two ids so they sanitize to distinct names."
+		},
+		DF0048: {
+			why: (p) => `Unknown shared-state key "${p.key}".`,
+			fix: "Call the devframe_state_read tool without arguments to list the available keys, then retry with one of them."
+		},
+		DF0049: {
+			why: "The devframe_connect_call-tool tool requires { port: number, tool: string }.",
+			fix: "Call devframe_connect_list-instances to get the port and tool names, then retry."
+		},
+		DF0050: {
+			why: (p) => `No running devframe instance on port ${p.port}.`,
+			fix: "Call devframe_connect_list-instances for the current instance list — the instance may have stopped or changed port."
+		},
+		DF0051: {
+			why: (p) => `The devframe instance on port ${p.port} has no MCP endpoint.`,
+			fix: "Restart the instance with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again."
+		}
+	}
+});
+//#endregion
+export { diagnostics as t };

package/dist/{diagnostics-BXwBQmoN.mjs → diagnostics-hwjXp_UV.mjs}

@@ -26,6 +26,14 @@ const diagnostics = defineDiagnostics({
 		DF0028: {
 			why: (p) => `Function "${p.name}" with type "${p.type}" cannot use \`snapshot: true\`. Only "query" functions support this sugar; "static" functions have equivalent default behavior already.`,
 			fix: "Remove `snapshot: true`, or change the function type to `query`."
+		},
+		DF0043: {
+			why: (p) => `RPC function "${p.name}" received an invalid argument at position ${p.index}: ${p.issues}`,
+			fix: "Pass a value that satisfies the `args` schema declared for this function."
+		},
+		DF0044: {
+			why: (p) => `RPC function "${p.name}" returned a value that failed its \`returns\` schema: ${p.issues}`,
+			fix: "Make the handler return a value that satisfies the `returns` schema, or relax the schema."
 		}
 	}
 });

package/dist/{dump-Cz7yVvsB.mjs → dump-CgZShDRB.mjs}

@@ -1,4 +1,4 @@
-import { t as diagnostics } from "./diagnostics-BXwBQmoN.mjs";
+import { t as diagnostics } from "./diagnostics-hwjXp_UV.mjs";
 import { DEVFRAME_RPC_DUMP_DIRNAME } from "./constants.mjs";
 import { createHash } from "node:crypto";
 //#region ../../node_modules/.pnpm/ohash@2.0.11/node_modules/ohash/dist/shared/ohash.D__AXeF1.mjs
@@ -498,6 +498,70 @@ function getDefinitionsWithDumps(definitions) {
 	return definitions.filter((def) => def.dump !== void 0);
 }
 //#endregion
+//#region src/rpc/validate-io.ts
+/**
+* Run a single [Standard Schema](https://standardschema.dev) validator,
+* awaiting the result when the validator is asynchronous.
+*/
+async function runStandardSchema(schema, value) {
+	const result = schema["~standard"].validate(value);
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Render Standard Schema issues into a single human-readable line for a
+* diagnostic message, prefixing each with its dotted path when present.
+*/
+function formatIssues(issues) {
+	return issues.map((issue) => {
+		const path = issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+/**
+* 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
+*/
+async function validateRpcArgs(name, argsSchema, args) {
+	const original = args.slice();
+	if (!argsSchema || argsSchema.length === 0) return original;
+	for (let index = 0; index < argsSchema.length; index++) {
+		const schema = argsSchema[index];
+		if (!schema) continue;
+		const result = await runStandardSchema(schema, args[index]);
+		if (result.issues) throw diagnostics.DF0043({
+			name,
+			index,
+			issues: formatIssues(result.issues)
+		});
+	}
+	return original;
+}
+/**
+* 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
+*/
+async function validateRpcReturn(name, returnSchema, value) {
+	if (!returnSchema) return value;
+	const result = await runStandardSchema(returnSchema, value);
+	if (result.issues) throw diagnostics.DF0044({
+		name,
+		issues: formatIssues(result.issues)
+	});
+	return value;
+}
+//#endregion
 //#region src/rpc/handler.ts
 async function getRpcResolvedSetupResult(definition, context) {
 	if (!definition.setup) return {};
@@ -524,10 +588,22 @@ async function getRpcResolvedSetupResult(definition, context) {
 	return await definition.__promise;
 }
 async function getRpcHandler(definition, context) {
-	if (definition.handler) return definition.handler;
-	const result = await getRpcResolvedSetupResult(definition, context);
-	if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
-	return result.handler;
+	let handler = definition.handler;
+	if (!handler) {
+		const result = await getRpcResolvedSetupResult(definition, context);
+		if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
+		handler = result.handler;
+	}
+	const argsSchema = definition.args;
+	const returnSchema = definition.returns;
+	if (!argsSchema && !returnSchema) return handler;
+	const inner = handler;
+	const validating = async (...args) => {
+		const validatedArgs = await validateRpcArgs(definition.name, argsSchema, args);
+		const output = await inner(...validatedArgs);
+		return await validateRpcReturn(definition.name, returnSchema, output);
+	};
+	return validating;
 }
 //#endregion
 //#region src/rpc/dump/static.ts
@@ -607,4 +683,4 @@ async function collectStaticRpcDump(definitions, context) {
 	};
 }
 //#endregion
-export { dumpFunctions as a, serializeDumpError as c, hash as d, createClientFromDump as i, validateDefinition as l, getRpcHandler as n, getDefinitionsWithDumps as o, getRpcResolvedSetupResult as r, reviveDumpError as s, collectStaticRpcDump as t, validateDefinitions as u };
+export { validateRpcReturn as a, getDefinitionsWithDumps as c, validateDefinition as d, validateDefinitions as f, validateRpcArgs as i, reviveDumpError as l, getRpcHandler as n, createClientFromDump as o, hash as p, getRpcResolvedSetupResult as r, dumpFunctions as s, collectStaticRpcDump as t, serializeDumpError as u };