veryfront 0.1.141 → 0.1.142

package/esm/cli/mcp/tools/dev-tools.js

@@ -15,11 +15,18 @@ const hotReloadInput = z.object({
     file: z
         .string()
         .optional()
-        .describe("Specific file to trigger reload for (optional - reloads all if not specified)"),
+        .describe("Specific file to trigger reload for. Example: 'app/page.tsx'. Omit to reload all."),
 });
 export const vfHotReload = {
     name: "vf_hot_reload",
-    description: "Trigger a hot reload of the dev server. Use after making changes to see them instantly.",
+    title: "Hot Reload",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to signal that a hot reload should occur. Note: currently a no-op stub that returns success without triggering an actual reload. For file-level HMR that sends a WebSocket update, use vf_trigger_hmr instead.",
     inputSchema: hotReloadInput,
     execute: () => Promise.resolve({
         success: true,
@@ -39,7 +46,9 @@ const getDebugContextInput = z.object({
 });
 export const vfGetDebugContext = {
     name: "vf_get_debug_context",
-    description: "Get the current server context including project info, environment, and mode. Useful for debugging server configuration issues.",
+    title: "Debug Context",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need the dev server's debug context including project slug, environment, request context mode, and multi-project configuration. Returns project info and server mode. Do not use for error details — use vf_get_errors instead.",
     inputSchema: getDebugContextInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_get_debug_context", async () => {
         const host = input.project ? `${input.project}.veryfront.me` : "veryfront.me";
@@ -72,12 +81,19 @@ export const vfGetDebugContext = {
 // Tool: vf_trigger_hmr
 // ============================================================================
 const triggerHmrInput = z.object({
-    path: z.string().describe("File path that changed (e.g., 'app/page.tsx')"),
+    path: z.string().describe("File path that changed. Example: 'app/page.tsx'."),
     port: z.number().int().min(1).max(65535).optional().default(8080).describe("Dev server port (defaults to 8080)"),
 });
 export const vfTriggerHmr = {
     name: "vf_trigger_hmr",
-    description: "Trigger Hot Module Replacement for a specific file. The browser will update without a full reload.",
+    title: "Trigger HMR",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to force an HMR update for a specific file path. Sends a WebSocket reload notification to connected browsers. Returns success status and active listener count. Do not use if no browser is connected — check vf_get_flywheel_status first.",
     inputSchema: triggerHmrInput,
     execute: (input) => {
         const metrics = ReloadNotifier.getMetrics();
@@ -98,17 +114,19 @@ export const vfTriggerHmr = {
 // Tool: vf_preview_route
 // ============================================================================
 const previewRouteInput = z.object({
-    route: z.string().startsWith("/", "Route must start with /").describe("Route path to preview (e.g., '/', '/dashboard', '/api/users')"),
+    route: z.string().startsWith("/", "Route must start with /").describe("Route path to preview. Example: '/', '/dashboard', '/api/users'."),
     port: z.number().int().min(1).max(65535).optional().default(8080).describe("Dev server port (defaults to 8080)"),
     format: z
         .enum(["html", "json", "status"])
         .optional()
         .default("status")
-        .describe("Output format: html (full page), json (API response), status (just HTTP status)"),
+        .describe("Output format: 'html' for full page, 'json' for API response, 'status' for just HTTP status. Defaults to 'status'."),
 });
 export const vfPreviewRoute = {
     name: "vf_preview_route",
-    description: "Preview a route by making a request to the dev server. Returns the rendered output, HTTP status, and render time. Perfect for testing changes instantly.",
+    title: "Preview Route",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to test-render a route and inspect the response. Returns rendered output, HTTP status, and render time. Note: API routes may have side effects. Do not use for listing routes — use vf_list_routes instead.",
     inputSchema: previewRouteInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_preview_route", async () => {
         const url = `http://localhost:${input.port}${input.route}`;
@@ -165,7 +183,9 @@ const waitForReadyInput = z.object({
 });
 export const vfWaitForReady = {
     name: "vf_wait_for_ready",
-    description: "Wait for the server to be ready by polling the health endpoint. Use this after starting the server to ensure it's accepting requests.",
+    title: "Wait for Ready",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to wait for the dev server to become ready after restart. Polls the health endpoint until responsive. Returns success status and elapsed time. Do not use for error counts or uptime — use vf_get_status instead.",
     inputSchema: waitForReadyInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_wait_for_ready", async () => {
         const startTime = Date.now();
@@ -202,7 +222,9 @@ const getFlywheelStatusInput = z.object({
 });
 export const vfGetFlywheelStatus = {
     name: "vf_get_flywheel_status",
-    description: "Get aggregated status for the development flywheel. Shows server state, error counts, log summary, and HMR status in one view.",
+    title: "Flywheel Status",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need a comprehensive status overview combining server health, error counts, and HMR statistics. Returns server status, error/log counts, and HMR metrics in one response. Do not use for detailed error or log content — use vf_get_errors or vf_get_logs instead.",
     inputSchema: getFlywheelStatusInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_get_flywheel_status", async () => {
         const port = input.port;

package/esm/cli/mcp/tools/introspection-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"introspection-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/introspection-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAyCzD,eAAO,MAAM,kBAAkB,EAAE,OAAO,EAGvC,CAAC"}
+{"version":3,"file":"introspection-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/introspection-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AA8CzD,eAAO,MAAM,kBAAkB,EAAE,OAAO,EAGvC,CAAC"}

package/esm/cli/mcp/tools/introspection-tools.js

@@ -7,7 +7,9 @@ const getSchemaInput = z.object({
 });
 const vfGetSchema = {
     name: "vf_get_schema",
-    description: "Get the CLI command schema for discovering available commands, arguments, and flags.",
+    title: "Get CLI Schema",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to discover available CLI commands, their arguments, and flags. Returns the command schema as JSON. Do not use for project info — use vf_get_project_info instead.",
     inputSchema: getSchemaInput,
     execute: async (input) => {
         if (input.command) {
@@ -19,7 +21,9 @@ const vfGetSchema = {
 const getProjectInfoInput = z.object({});
 const vfGetProjectInfo = {
     name: "vf_get_project_info",
-    description: "Get project metadata including project slug, version, and environment.",
+    title: "Get Project Info",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need project metadata including project slug, version, and environment. Returns slug, version, and environment config. Do not use for CLI commands — use vf_get_schema instead.",
     inputSchema: getProjectInfoInput,
     execute: async () => {
         const { getEnvironmentConfig } = await import("../../../src/config/index.js");

package/esm/cli/mcp/tools/project-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/project-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAKL,KAAK,cAAc,EAEnB,KAAK,SAAS,EAGf,MAAM,cAAc,CAAC;AAMtB,QAAA,MAAM,eAAe;;;;;;;;iBAOnB,CAAC;AAEH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEvD,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE,SAAS,EAAE,CAyB9D,CAAC;AAMF,QAAA,MAAM,sBAAsB;;iBAI1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAoErE,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,cAAc,CAgC/E,CAAC;AAMF,QAAA,MAAM,qBAAqB;;;iBAKzB,CAAC;AAEH,KAAK,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAiBD,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,qBAAqB,EAAE,mBAAmB,CAsDlF,CAAC;AAMF,QAAA,MAAM,sBAAsB;;;iBAO1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8ED,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,gBAAgB,EAAE,CAenF,CAAC"}
+{"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/project-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAKL,KAAK,cAAc,EAEnB,KAAK,SAAS,EAGf,MAAM,cAAc,CAAC;AAMtB,QAAA,MAAM,eAAe;;;;;;;;iBAOnB,CAAC;AAEH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEvD,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE,SAAS,EAAE,CA2B9D,CAAC;AAMF,QAAA,MAAM,sBAAsB;;iBAI1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAoErE,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,cAAc,CAkC/E,CAAC;AAMF,QAAA,MAAM,qBAAqB;;;iBAKzB,CAAC;AAEH,KAAK,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAiBD,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,qBAAqB,EAAE,mBAAmB,CAwDlF,CAAC;AAMF,QAAA,MAAM,sBAAsB;;;iBAO1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8ED,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,gBAAgB,EAAE,CAiBnF,CAAC"}

package/esm/cli/mcp/tools/project-tools.js

@@ -15,7 +15,9 @@ const listRoutesInput = z.object({
 });
 export const vfListRoutes = {
     name: "vf_list_routes",
-    description: "Discover all routes in the project. Returns pages, API routes, layouts, and special routes. Use this to understand the project structure before making changes.",
+    title: "List Routes",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to discover all routes in the project including pages, API routes, layouts, error, loading, and not-found routes. Returns an array of route info with path, type, and file. Do not use for rendering a route — use vf_preview_route instead.",
     inputSchema: listRoutesInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_list_routes", async () => {
         const projectDir = getProjectDir(input.projectPath);
@@ -95,7 +97,9 @@ async function getProjectName(projectDir, fs) {
 }
 export const vfGetProjectContext = {
     name: "vf_get_project_context",
-    description: "Get deep understanding of the project structure, conventions, and capabilities. Use this at the start of any coding session to understand the project before making changes.",
+    title: "Project Context",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to understand the project structure, conventions, and capabilities at the start of a coding session. Also returns route information. Do not use for detailed per-route rendering — use vf_preview_route instead.",
     inputSchema: getProjectContextInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_get_project_context", async () => {
         const projectDir = getProjectDir(input.projectPath);
@@ -136,7 +140,9 @@ function toRelativePath(absolutePath, projectDir) {
 }
 export const vfGetComponentTree = {
     name: "vf_get_component_tree",
-    description: "Analyze the component hierarchy for a route. Shows layouts, providers, and components that render on this route. Helps understand the rendering structure.",
+    title: "Component Tree",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to analyze the component hierarchy for a specific route including layouts, providers, and nested components. Returns the component tree structure. Do not use for listing all routes — use vf_list_routes instead.",
     inputSchema: getComponentTreeInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_get_component_tree", async () => {
         const projectDir = getProjectDir(input.projectPath);
@@ -262,7 +268,9 @@ async function scanForProjects(baseDir, depth, projects) {
 }
 export const vfListLocalProjects = {
     name: "vf_list_local_projects",
-    description: "Discover Veryfront projects on the local filesystem. Scans for veryfront.config.ts files and returns project info including template type and integrations.",
+    title: "List Local Projects",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to discover Veryfront projects on the local filesystem by scanning for veryfront.config.ts files. Returns project info including template type and integrations. Do not use for project structure details — use vf_get_project_context instead.",
     inputSchema: listLocalProjectsInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_list_local_projects", async () => {
         const projects = [];

package/esm/cli/mcp/tools/scaffold-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/scaffold-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAML,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AAkItB,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;iBAajB,CAAC;AAEH,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AA+CnD,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,aAAa,EAAE,cAAc,CA+C7D,CAAC;AAMF,QAAA,MAAM,mBAAmB;;;;;;;;;iBAMvB,CAAC;AAEH,KAAK,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AA4HD,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,mBAAmB,EAAE,UAAU,EAAE,CAavE,CAAC"}
+{"version":3,"file":"scaffold-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/scaffold-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAML,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AAkItB,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;iBAajB,CAAC;AAEH,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AA+CnD,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,aAAa,EAAE,cAAc,CAiD7D,CAAC;AAMF,QAAA,MAAM,mBAAmB;;;;;;;;;iBAMvB,CAAC;AAEH,KAAK,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AA4HD,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,mBAAmB,EAAE,UAAU,EAAE,CAevE,CAAC"}

package/esm/cli/mcp/tools/scaffold-tools.js

@@ -167,7 +167,9 @@ const SCAFFOLD_CONFIGS = {
 };
 export const vfScaffold = {
     name: "vf_scaffold",
-    description: "Generate new entities (pages, API routes, layouts, components, AI tools, agents, prompts) with proper conventions. This is the recommended way to create new files in a Veryfront project.",
+    title: "Scaffold Code",
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    description: "Use this when you need to generate new pages, API routes, layouts, components, AI tools, agents, or prompts with proper Veryfront conventions. Returns the created file path and content. May overwrite existing files at the target path. Do not use for creating entire projects — use vf_create_project instead.",
     inputSchema: scaffoldInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_scaffold", async () => {
         const projectDir = getProjectDir(input.projectPath);
@@ -337,7 +339,9 @@ const CONVENTIONS = {
 };
 export const vfGetConventions = {
     name: "vf_get_conventions",
-    description: "Get Veryfront coding conventions and best practices. Use this as guardrails when writing code to ensure consistency with the project standards.",
+    title: "Get Conventions",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need Veryfront coding conventions and best practices for routing, API, components, AI, or styling. Do not use for project structure — use vf_get_project_context instead.",
     inputSchema: getConventionsInput,
     execute: (input) => {
         if (input.topic === "all")

package/esm/cli/mcp/tools/skill-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/skill-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAwD3C,QAAA,MAAM,cAAc;;iBAIlB,CAAC;AAEH,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,UAAU,YAAa,SAAQ,aAAa;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,CA+DhE,CAAC;AAEF,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,UAAU,uBAAuB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,uBAAuB,CAgBxF,CAAC"}
+{"version":3,"file":"skill-tools.d.ts","sourceRoot":"","sources":["../../../../src/cli/mcp/tools/skill-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAwD3C,QAAA,MAAM,cAAc;;iBAIlB,CAAC;AAEH,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,UAAU,YAAa,SAAQ,aAAa;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,eAAe,CAiEhE,CAAC;AAEF,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,UAAU,uBAAuB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,sBAAsB,EAAE,uBAAuB,CAkBxF,CAAC"}

package/esm/cli/mcp/tools/skill-tools.js

@@ -54,7 +54,9 @@ const getSkillsInput = z.object({
 });
 export const vfGetSkills = {
     name: "vf_get_skills",
-    description: "Discover available Agent Skills for Veryfront development. Skills provide procedural knowledge for using MCP tools effectively. Call without name param to list all skills, or with name to get full skill content.",
+    title: "Get Skills",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to discover available Agent Skills or load a specific skill's procedural knowledge. Returns skill names and descriptions, or full skill content when name is provided. Do not use for skill reference docs — use vf_get_skill_reference instead.",
     inputSchema: getSkillsInput,
     execute: (input) => withSpan("cli.mcp.tool.vf_get_skills", async () => {
         const fs = getFs();
@@ -113,7 +115,9 @@ const getSkillReferenceInput = z.object({
 });
 export const vfGetSkillReference = {
     name: "vf_get_skill_reference",
-    description: "Get a specific reference document from a skill. Use this to load detailed documentation on demand.",
+    title: "Get Skill Reference",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to load a specific reference document from a skill. Returns the document content as text. Do not use for skill discovery — use vf_get_skills instead.",
     inputSchema: getSkillReferenceInput,
     execute: async (input) => {
         const fs = getFs();

package/esm/cli/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/tools.ts"],"names":[],"mappings":"AAAA;;4BAE4B;AAE5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,QAAQ,EAIb,KAAK,QAAQ,EAEd,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAMtD,YAAY,EAAE,OAAO,EAAE,CAAC;AAUxB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,QAAA,MAAM,cAAc;;;;;;;;;;iBAMlB,CAAC;AAEH,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,QAAQ,EAAE,CAc3D,CAAC;AAEF,QAAA,MAAM,YAAY;;;;;;;;;;;iBAQhB,CAAC;AAEH,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEjD,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,CAcvD,CAAC;AAEF,QAAA,MAAM,eAAe;;;;;;iBAInB,CAAC;AAEH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEvD,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE,gBAAgB,CAsBnE,CAAC;AAEF,QAAA,MAAM,cAAc,gCAAe,CAAC;AAEpC,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,iBAA0C,GAC9C,OAAO,CAAC,cAAc,EAAE,YAAY,CAAC,CAsBvC;AAED,eAAO,MAAM,WAAW,8CAAsB,CAAC;AAE/C,QAAA,MAAM,gBAAgB;;;;;;;;;iBAKpB,CAAC;AAEH,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEzD,UAAU,iBAAiB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,gBAAgB,EAAE,iBAAiB,CActE,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,OAAO,EAS7B,CAAC;AAEF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED,wBAAgB,SAAS,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAExE"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/tools.ts"],"names":[],"mappings":"AAAA;;4BAE4B;AAE5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,QAAQ,EAIb,KAAK,QAAQ,EAEd,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAMtD,YAAY,EAAE,OAAO,EAAE,CAAC;AAUxB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,QAAA,MAAM,cAAc;;;;;;;;;;iBAUlB,CAAC;AAEH,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,cAAc,EAAE,QAAQ,EAAE,CAgB3D,CAAC;AAEF,QAAA,MAAM,YAAY;;;;;;;;;;;iBAgBhB,CAAC;AAEH,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEjD,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,CAgBvD,CAAC;AAEF,QAAA,MAAM,eAAe;;;;;;iBAInB,CAAC;AAEH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEvD,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE,gBAAgB,CA6BnE,CAAC;AAEF,QAAA,MAAM,cAAc,gCAAe,CAAC;AAEpC,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAErD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,iBAA0C,GAC9C,OAAO,CAAC,cAAc,EAAE,YAAY,CAAC,CAyBvC;AAED,eAAO,MAAM,WAAW,8CAAsB,CAAC;AAE/C,QAAA,MAAM,gBAAgB;;;;;;;;;iBAOpB,CAAC;AAEH,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEzD,UAAU,iBAAiB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,gBAAgB,EAAE,iBAAiB,CAsBtE,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,OAAO,EAS7B,CAAC;AAEF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED,wBAAgB,SAAS,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAExE"}

package/esm/cli/mcp/tools.js

@@ -19,13 +19,15 @@ export function setServerStartTime(time) {
     serverStartTime = time;
 }
 const getErrorsInput = z.object({
-    type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe("Filter by error type"),
-    file: z.string().optional().describe("Filter by file path"),
-    limit: z.number().optional().default(50).describe("Maximum number of errors to return"),
+    type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe("Filter by error type. Example: 'compile'. Omit to return all types."),
+    file: z.string().optional().describe("Filter by file path. Example: 'app/page.tsx'. Omit to return errors from all files."),
+    limit: z.number().optional().default(50).describe("Maximum number of errors to return. Defaults to 50."),
 });
 export const vfGetErrors = {
     name: "vf_get_errors",
-    description: "Get compilation, runtime, and build errors from the dev server. Use this to debug issues with your code.",
+    title: "Get Errors",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to check for compilation, runtime, bundle, HMR, or module errors in the dev server. Returns error details including file path, line number, and message. Do not use for server logs — use vf_get_logs instead.",
     inputSchema: getErrorsInput,
     execute: async (input) => {
         const errors = getErrorCollector().getAll({
@@ -38,15 +40,17 @@ export const vfGetErrors = {
     },
 };
 const getLogsInput = z.object({
-    level: z.enum(["debug", "info", "warn", "error"]).optional().describe("Filter by log level"),
-    source: z.string().optional().describe("Filter by log source (e.g., 'server', 'hmr', 'transform')"),
-    pattern: z.string().optional().describe("Filter by pattern (case-insensitive substring match)"),
-    limit: z.number().optional().default(100).describe("Maximum number of log entries to return"),
-    since: z.number().optional().describe("Only return logs after this timestamp"),
+    level: z.enum(["debug", "info", "warn", "error"]).optional().describe("Filter by log level. Example: 'error'. Omit to return all levels."),
+    source: z.string().optional().describe("Filter by log source. Example: 'server', 'hmr', 'transform'. Omit to return all sources."),
+    pattern: z.string().optional().describe("Filter by pattern (case-insensitive substring match). Example: 'timeout'."),
+    limit: z.number().optional().default(100).describe("Maximum number of log entries to return. Defaults to 100."),
+    since: z.number().optional().describe("Only return logs after this Unix timestamp in milliseconds."),
 });
 export const vfGetLogs = {
     name: "vf_get_logs",
-    description: "Get recent server logs. Use this to understand what the server is doing and debug runtime issues.",
+    title: "Get Logs",
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    description: "Use this when you need to inspect server logs to understand runtime behavior or debug request handling. Returns log entries with timestamp, level, source, and message. Do not use for build/compile errors — use vf_get_errors instead.",
     inputSchema: getLogsInput,
     execute: async (input) => {
         return getLogBuffer().query({
@@ -59,11 +63,18 @@ export const vfGetLogs = {
     },
 };
 const clearCacheInput = z.object({
-    type: z.enum(["all", "modules", "mdx"]).optional().default("all").describe("Type of cache to clear"),
+    type: z.enum(["all", "modules", "mdx"]).optional().default("all").describe("Type of cache to clear. Example: 'modules'. Defaults to 'all'."),
 });
 export const vfClearCache = {
     name: "vf_clear_cache",
-    description: "Clear module and build caches. Use this when changes aren't being reflected or to force a rebuild.",
+    title: "Clear Cache",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when the dev server shows stale modules or MDX content. Returns the list of cleared cache directories. Do not use to fix code errors — those require code changes.",
     inputSchema: clearCacheInput,
     execute: async (input) => {
         const fs = createFileSystem();
@@ -86,7 +97,9 @@ const getStatusInput = z.object({});
 export function createVfGetStatus(env = getEnvironmentConfig()) {
     return {
         name: "vf_get_status",
-        description: "Get the current status of the dev server including error counts and uptime.",
+        title: "Server Status",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        description: "Use this when you need a quick summary of the dev server's uptime, error counts, and warning counts. Note: always reports running=true when the MCP server is reachable. Do not use for detailed error info — use vf_get_errors instead.",
         inputSchema: getStatusInput,
         execute: async () => {
             const errors = getErrorCollector();
@@ -107,12 +120,19 @@ export function createVfGetStatus(env = getEnvironmentConfig()) {
 }
 export const vfGetStatus = createVfGetStatus();
 const clearErrorsInput = z.object({
-    file: z.string().optional().describe("Clear errors for a specific file only"),
-    type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe("Clear errors of a specific type only"),
+    file: z.string().optional().describe("Clear errors for a specific file only. Example: 'app/page.tsx'. Omit to clear all files."),
+    type: z.enum(["compile", "runtime", "bundle", "hmr", "module"]).optional().describe("Clear errors of a specific type only. Example: 'compile'. Omit to clear all types."),
 });
 export const vfClearErrors = {
     name: "vf_clear_errors",
-    description: "Clear errors from the error collector. Useful after fixing issues.",
+    title: "Clear Errors",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Use this when you need to clear accumulated errors from the error collector, optionally filtering by file or type. Returns the number of cleared errors. Do not use for viewing errors — use vf_get_errors instead.",
     inputSchema: clearErrorsInput,
     execute: async (input) => {
         const collector = getErrorCollector();

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.141",
+    "version": "0.1.142",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "exclude": [

package/esm/src/agent/runtime/index.js

@@ -272,7 +272,7 @@ export class AgentRuntime {
                     logger.error("Agent stream error", { error });
                     sendSSE(controller, encoder, {
                         type: "error",
-                        error: "An internal error occurred",
+                        error: error instanceof Error ? error.message : String(error),
                     });
                     closeSSEStream(controller);
                 }

package/esm/src/agent/runtime/tool-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../../../src/src/agent/runtime/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAYtF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,cAAc,CAuBhB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AAEH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC;AAEvD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,QAAQ,EAAE,MAAM,GACf,IAAI,GAAG,IAAI,CAmBb;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,OAAO,CAAC,EAAE,oBAAoB,EAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,GAChC,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAoBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,OAAO,CAAC,EAAE;IACR,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC,GACA,OAAO,CAAC,cAAc,EAAE,CAAC,CA4E3B"}
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../../../src/src/agent/runtime/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAatF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,cAAc,CAuBhB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AAEH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC;AAgDvD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,QAAQ,EAAE,MAAM,GACf,IAAI,GAAG,IAAI,CAmBb;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,OAAO,CAAC,EAAE,oBAAoB,EAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,GAChC,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAoBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,EAC/D,OAAO,CAAC,EAAE;IACR,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC,GACA,OAAO,CAAC,cAAc,EAAE,CAAC,CA+E3B"}

package/esm/src/agent/runtime/tool-helpers.js

@@ -9,6 +9,7 @@ import { executeTool, toolRegistry } from "../../tool/index.js";
 import { toolToProviderDefinition } from "../../tool/registry.js";
 import { SKILL_TOOL_IDS } from "../../skill/types.js";
 import { serverLogger } from "../../utils/index.js";
+import { createError, toError } from "../../errors/veryfront-error.js";
 import { executeRemoteIntegrationTool, isRemoteIntegrationTool, } from "../../integrations/remote-tools.js";
 const logger = serverLogger.component("agent");
 /**
@@ -43,6 +44,34 @@ export function parseToolArgs(rawArgs) {
 export function isDynamicTool(name) {
     return toolRegistry.get(name)?.type === "dynamic";
 }
+function formatAvailableToolNames(names) {
+    const sorted = [...new Set(names)].sort();
+    return sorted.length > 0 ? sorted.join(", ") : "(none)";
+}
+function throwUnknownConfiguredToolsError(unknownToolNames, availableLocalToolNames, availableRemoteToolNames) {
+    const unknownList = unknownToolNames.sort().join(", ");
+    const availableNames = formatAvailableToolNames([
+        ...availableLocalToolNames,
+        ...availableRemoteToolNames,
+    ]);
+    throw toError(createError({
+        type: "agent",
+        message: `Unknown tool reference${unknownToolNames.length === 1 ? "" : "s"}: ${unknownList}. ` +
+            `Tool names must exactly match tool({ id: "..." }). Available tools: ${availableNames}`,
+    }));
+}
+async function getRemoteToolDefinitions(options) {
+    if (options?.includeIntegrationTools === false) {
+        return [];
+    }
+    try {
+        const { getRemoteIntegrationToolDefinitions } = await import("../../integrations/remote-tools.js");
+        return (await getRemoteIntegrationToolDefinitions()).filter((def) => !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name));
+    }
+    catch {
+        return [];
+    }
+}
 export function resolveConfiguredTool(toolsConfig, toolName) {
     if (!toolsConfig) {
         return null;
@@ -113,51 +142,51 @@ export async function getAvailableTools(toolsConfig, options) {
             return true;
         });
         // Append remote integration tools (per-request, project-scoped)
-        if (options?.includeIntegrationTools !== false) {
-            try {
-                const { getRemoteIntegrationToolDefinitions } = await import("../../integrations/remote-tools.js");
-                const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) => !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name));
-                for (const def of remoteDefs) {
-                    logToolDefinition(def.name, def);
-                }
-                tools.push(...remoteDefs);
-            }
-            catch {
-                // Integration tools unavailable — non-fatal
-            }
+        const remoteDefs = await getRemoteToolDefinitions(options);
+        for (const def of remoteDefs) {
+            logToolDefinition(def.name, def);
         }
+        tools.push(...remoteDefs);
         return tools;
     }
     const tools = [];
+    const remoteDefs = await getRemoteToolDefinitions(options);
+    const remoteToolNames = new Set(remoteDefs.map((def) => def.name));
+    const explicitlyRequestedRemoteToolNames = new Set();
+    const unresolvedConfiguredToolNames = [];
     for (const [name, entry] of Object.entries(toolsConfig)) {
         if (entry === true) {
             const tool = toolRegistry.get(name);
-            if (tool)
+            if (tool) {
                 addToolDefinition(tools, name, tool);
+                continue;
+            }
+            if (remoteToolNames.has(name)) {
+                explicitlyRequestedRemoteToolNames.add(name);
+                continue;
+            }
+            unresolvedConfiguredToolNames.push(name);
             continue;
         }
         if (entry && typeof entry === "object") {
             addToolDefinition(tools, name, entry);
         }
     }
-    // Also append remote integration tools for explicit-object configs.
-    // The internal streaming path converts `tools: true` to an explicit object
-    // from the local registry, so remote tools would be missed without this.
-    if (options?.includeIntegrationTools !== false) {
-        try {
-            const { getRemoteIntegrationToolDefinitions } = await import("../../integrations/remote-tools.js");
-            const remoteDefs = (await getRemoteIntegrationToolDefinitions()).filter((def) => !options?.allowedRemoteToolNames || options.allowedRemoteToolNames.includes(def.name));
-            for (const def of remoteDefs) {
-                // Skip if already present (e.g., explicitly configured by name)
-                if (!tools.some((t) => t.name === def.name)) {
-                    logToolDefinition(def.name, def);
-                    tools.push(def);
-                }
-            }
-        }
-        catch {
-            // Integration tools unavailable — non-fatal
+    // Explicit-object configs should only expose remote definitions that were
+    // explicitly requested, except for the internal runtime path that expands
+    // `tools: true` into an explicit local-tool map and passes the remote allowlist.
+    const remoteDefsToAppend = explicitlyRequestedRemoteToolNames.size > 0
+        ? remoteDefs.filter((def) => explicitlyRequestedRemoteToolNames.has(def.name))
+        : remoteDefs.filter((def) => options?.allowedRemoteToolNames?.includes(def.name));
+    for (const def of remoteDefsToAppend) {
+        // Skip if already present (e.g., explicitly configured by name)
+        if (!tools.some((t) => t.name === def.name)) {
+            logToolDefinition(def.name, def);
+            tools.push(def);
         }
     }
+    if (unresolvedConfiguredToolNames.length > 0) {
+        throwUnknownConfiguredToolsError(unresolvedConfiguredToolNames, toolRegistry.getAll().keys(), remoteToolNames);
+    }
     return tools;
 }

package/esm/src/agent/schemas/agent.schema.d.ts

@@ -7,11 +7,11 @@ export declare const modelProviderSchema: z.ZodEnum<{
 }>;
 export declare const agentStatusSchema: z.ZodEnum<{
     error: "error";
+    completed: "completed";
     idle: "idle";
     thinking: "thinking";
     tool_execution: "tool_execution";
     streaming: "streaming";
-    completed: "completed";
 }>;
 export declare const MemoryConfigSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -128,9 +128,9 @@ export declare const ToolCallSchema: z.ZodObject<{
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     status: z.ZodEnum<{
         error: "error";
-        completed: "completed";
         pending: "pending";
         executing: "executing";
+        completed: "completed";
     }>;
     result: z.ZodOptional<z.ZodUnknown>;
     error: z.ZodOptional<z.ZodString>;
@@ -179,9 +179,9 @@ export declare const AgentResponseSchema: z.ZodObject<{
         args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         status: z.ZodEnum<{
             error: "error";
-            completed: "completed";
             pending: "pending";
             executing: "executing";
+            completed: "completed";
         }>;
         result: z.ZodOptional<z.ZodUnknown>;
         error: z.ZodOptional<z.ZodString>;
@@ -189,11 +189,11 @@ export declare const AgentResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
     status: z.ZodEnum<{
         error: "error";
+        completed: "completed";
         idle: "idle";
         thinking: "thinking";
         tool_execution: "tool_execution";
         streaming: "streaming";
-        completed: "completed";
     }>;
     thinking: z.ZodOptional<z.ZodString>;
     usage: z.ZodOptional<z.ZodObject<{

package/esm/src/channels/invoke.d.ts

@@ -71,9 +71,9 @@ export declare const ChannelResponsePartSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     state: z.ZodEnum<{
         error: "error";
-        streaming: "streaming";
-        completed: "completed";
         pending: "pending";
+        completed: "completed";
+        streaming: "streaming";
     }>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_result">;
@@ -100,9 +100,9 @@ export declare const ChannelInvokeResponseSchema: z.ZodObject<{
         input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         state: z.ZodEnum<{
             error: "error";
-            streaming: "streaming";
-            completed: "completed";
             pending: "pending";
+            completed: "completed";
+            streaming: "streaming";
         }>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"tool_result">;

package/esm/src/issues/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/src/issues/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAoN/C;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EAOnC,CAAC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/src/issues/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAqP/C;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EAOnC,CAAC"}